MLB MCP Server

An MCP (Model Context Protocol) server that gives any MCP-capable LLM real-time access to MLB and MiLB baseball data via the free MLB Stats API (statsapi.mlb.com).

No API key required. No signup. No rate-limit keys. It just works.

Install

npm install @jerrysv/mlb-mcp-server

Or run directly with npx:

npx @jerrysv/mlb-mcp-server

Usage

Pass team names as arguments to track specific teams. The server fuzzy-matches names against the MLB Stats API at startup.

# Generic mode — all tools work, no pre-configured teams
npx @jerrysv/mlb-mcp-server

# Track specific teams by name
npx @jerrysv/mlb-mcp-server mariners diamondbacks "hillsboro hops"

# Track by team ID
npx @jerrysv/mlb-mcp-server 136 109 419

# Track by abbreviation
npx @jerrysv/mlb-mcp-server SEA ARI

# Mix and match
npx @jerrysv/mlb-mcp-server mariners 109 "hillsboro hops"

Team names are fuzzy-matched, so typos like "Diamonbacks" or "Seattel Mariners" will still resolve correctly. The server logs fuzzy matches to stderr so you can verify.

When teams are tracked, the server exposes them via get_tracked_teams and resolve_team for quick lookups. Without team args, the LLM can still discover any team via get_all_mlb_teams.

What you get

Tools (22)

Resources (3)

Prompts (3)

Prerequisites

• Node.js 18+ — check with node --version

That's it. No API keys needed.

Connecting to Claude Code

Add to ~/.claude.json or a project .mcp.json:

{
  "mcpServers": {
    "mlb": {
      "command": "npx",
      "args": [
        "@jerrysv/mlb-mcp-server",
        "mariners",
        "diamondbacks",
        "hillsboro hops"
      ]
    }
  }
}

Or without tracked teams:

{
  "mcpServers": {
    "mlb": {
      "command": "npx",
      "args": ["@jerrysv/mlb-mcp-server"]
    }
  }
}

Connecting to other MCP clients

Any MCP-compatible client (Ollama + Open WebUI, LM Studio, etc.) can use this server. It communicates over stdio:

npx @jerrysv/mlb-mcp-server mariners

Point your client's MCP config at that command.

Common team IDs

Use get_all_mlb_teams or get_sport_ids to discover any team.

Tool reference

Teams

• get_tracked_teams — List the teams this server is tracking with IDs, abbreviations, aliases, and league info.
• resolve_team (team) — Resolve a fuzzy team name or abbreviation to its canonical info. Only works for tracked teams.
• get_team_roster (team_id, roster_type?) — Get the active roster for a team. Roster types: active (default), fullSeason, fullRoster, depthChart, coach.
• get_all_mlb_teams (sport_id?) — List all teams for a league level. Sport IDs: 1=MLB, 11=AAA, 12=AA, 13=High-A, 14=Single-A.
• get_team_affiliates (team_id) — Get minor league affiliates for an MLB team. Shows the full farm system.

Players

• find_player (name, team?) — Search for any MLB/MiLB player by name. Returns person IDs, positions, teams, and basic bio. The best starting point for player lookups.
• get_player (person_id, season?) — Get full detailed info and season stats for a player by person ID.
• search_player_on_team (team_id, name) — Search for a player by name within a specific team's roster.

Games & Schedule

• get_games_today (sport_id?) — Get all games scheduled for today with scores and status.
• get_games_by_date (date, sport_id?) — Get all games for a specific date (YYYY-MM-DD format).
• get_team_schedule (team_id, start_date?, end_date?, sport_id?) — Get upcoming or past games for a team. Defaults to 14 days from start date.

Live Game Data

• get_game_feed (game_pk) — Full live game feed: scores, plays, decisions, linescore, weather, probable pitchers.
• get_box_score (game_pk) — Box score with batting, pitching, and fielding stats for both teams.
• get_line_score (game_pk) — Inning-by-inning runs, hits, and errors.
• get_play_by_play (game_pk) — Full play-by-play with scoring plays highlighted and last play summary.

Standings

• get_standings (season?) — Current MLB standings by division: wins, losses, PCT, games back, streak.

Stats & Leaders

• get_player_stats (person_id, season?) — Season stats (batting, pitching, fielding) for a player.
• get_team_stats (team_id, season?, group?) — Aggregate team stats. Group: hitting (default) or pitching.
• get_team_leaders (team_id, season?, category?) — Stat leaders on a team. Categories: homeRuns, battingAverage, earnedRunAverage, strikeouts, etc.
• get_league_leaders (category?, season?, stat_group?, limit?) — MLB-wide stat leaders. Categories: homeRuns, battingAverage, earnedRunAverage, strikeouts, wins, saves.

Transactions

• get_transactions (team_id?, start_date?, end_date?) — Recent transactions: trades, signings, call-ups, DFAs, IL moves. Defaults to last 7 days.

Venues

• get_venues — Info on MLB stadiums and ballparks.

Season & Reference

• get_current_season (season?) — Season metadata: start/end dates, all-star game, postseason dates.
• get_sport_ids — List all league levels with sport IDs (MLB=1, AAA=11, AA=12, High-A=13, etc).

Example conversations

"Are there any Mariners games today?" — calls get_games_today, then filters for SEA

"Tell me about Julio Rodriguez" — calls find_player("Julio Rodriguez") → person ID 677594, then get_player(677594)

"Show me the Mariners roster" — calls resolve_team("Mariners") → teamId 136, then get_team_roster(136)

"How are the D-backs doing this season?" — calls get_standings, finds ARI in NL West

"What are the Hillsboro Hops' upcoming games?" — calls get_team_schedule(419) with sportId 13

"Show me the farm system for Arizona" — calls get_team_affiliates(109)

"Give me the box score for game 777245" — calls get_box_score(777245)

"Who leads MLB in home runs?" — calls get_league_leaders(category: "homeRuns")

"Any recent Mariners transactions?" — calls get_transactions(team_id: 136)

Setup (from source)

git clone <repo-url>
cd mlb
npm install
npm test
node src/index.js mariners diamondbacks

Project structure

mlb/
  src/
    index.js        — MCP server (tools, resources, prompts)
    api-client.js   — HTTP client for statsapi.mlb.com
    teams.js        — Dynamic tracked team registry and fuzzy resolver
    helpers.js      — Date formatting, text helpers
  test/
    api-client.test.js
    helpers.test.js
    teams.test.js
  package.json
  README.md

Running tests

npm test

87 tests, zero external dependencies beyond @modelcontextprotocol/sdk. All API client tests mock fetch — no real network calls.

License

MIT