Statcast MCP Server

A MCP (Model Context Protocol) server that lets you query MLB Statcast data using plain English. Ask your AI assistant about players, games, stats, leaderboards, and more — no coding required.

Built on pybaseball, this server gives AI assistants direct access to data from Baseball Savant, FanGraphs, and Baseball Reference.

What Can You Ask?

Once connected, just talk to your AI assistant naturally:

• "How did Aaron Judge hit in July 2024?"

• "Show me Gerrit Cole's pitch arsenal this season"

• "Who had the highest exit velocity in 2024?"

• "What were the NL standings at the end of 2023?"

• "Find me the most undervalued hitters — compare xBA to actual BA"

• "Expected stats for the whole Yankees lineup and their five starters" (use expected_stats_batch with comma-separated names)

• "Who are the fastest players in baseball right now?"

• "Show me every pitch from the Yankees-Red Sox game on July 4, 2024"

The AI translates your questions into the right data queries automatically.

Example: Prompt & Response

Here's what a typical exchange looks like when you use the Statcast MCP:

Prompt

"What were Gerrit Cole's arsenal statistics in 2023?"

Response

His 4-seam fastball was his primary weapon (52.9% usage) with a .202 BA against and +1.7 run value per 100 pitches. The changeup was his only negative pitch (−1.3 run value).

Another prompt

"Who had the highest exit velocity in 2024?"

Response

The AI calls statcast_batter_exitvelo_barrels(year=2024) and returns the leaderboard — Aaron Judge led with a 97.0 mph average exit velocity and 21.8% barrel rate, followed by [other top hitters]...

Available Tools

46 tools total. Most tables support optional max_output_rows (per-tool defaults: 10 / 50 / 100 / 200 / 250 — see REFERENCE.md); values are clamped to 5000 max. Core table above; extended tools add schedules, splits, Lahman history, draft/prospects, WAR files, extra Statcast defense/movement, league team totals, single-game pitch logs, and batter–pitcher matchup summaries. Call statcast_tool_directory for the full list, or see TOOLS_SUMMARY.md and REFERENCE.md.

Extended tools (high level)

Team seasons: Use team_season_batting_stats / team_season_pitching_stats with a 3-letter code (PHI, NYY, …) for a full roster’s actual stats (lineup + staff). FanGraphs is tried first; Baseball Reference is used if FG fails or returns nothing.

Player search: Nearly every leaderboard/stat tool accepts optional player_name (e.g. "Aaron Judge") so you get that player’s full rows instead of only the first 50 in the table. For groups (full lineup + rotation, “all starters”), use expected_stats_batch with comma-separated names — the server does not pull MLB rosters automatically; list names explicitly or resolve them first (e.g. web / player_lookup). Pitch-level tools already take a name via statcast_batter / statcast_pitcher. team_standings is team-only.

Quick Start

Prerequisites

• Python 3.10+ — download here if you don't have it

• An MCP-compatible client — such as Claude Desktop, Cursor, or VS Code with Copilot

Option 1: Install from PyPI (Recommended)

# Using uv (fastest)
uv pip install statcast-mcp

# Or using pip
pip install statcast-mcp

Option 2: Install from Source

git clone https://github.com/YOUR_USERNAME/statcast-mcp.git
cd statcast-mcp
uv pip install .

Setup

Claude Desktop

Add this to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "statcast": {
      "command": "statcast-mcp"
    }
  }
}

If you installed from source and want to run it directly:

{
  "mcpServers": {
    "statcast": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/statcast-mcp", "statcast-mcp"]
    }
  }
}

Cursor

Open Cursor Settings → MCP and add a new server:

• Name: statcast

• Type: command

• Command: statcast-mcp

Or add to your .cursor/mcp.json:

{
  "mcpServers": {
    "statcast": {
      "command": "statcast-mcp"
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "statcast": {
        "command": "statcast-mcp"
      }
    }
  }
}

Example Queries

Looking Up a Player

"Look up Shohei Ohtani"

Returns the player's MLBAM ID, FanGraphs ID, Baseball Reference ID, and years active.

Pitch-Level Data

"Show me all the pitches from the Dodgers game on October 15, 2024"

statcast_search(start_date="2024-10-15", team="LAD")

Batter Analysis

"What pitches did Juan Soto see from July 1 to July 31, 2024?"

statcast_batter(player_name="Juan Soto", start_date="2024-07-01", end_date="2024-07-31")

"How does Aaron Judge hit against different pitch types?" (e.g. 2023, 106 games)

statcast_batter_pitch_arsenal(year=2023, player_name="Aaron Judge")

Season Leaderboards

"Who were the top hitters in 2024 by wRC+?"

season_batting_stats(start_season=2024)

"Top 200 hitters in 2023 by slugging, min 100 PA"

season_batting_stats(
    start_season=2023,
    min_plate_appearances=100,
    sort_by="SLG",
    max_output_rows=200,
)

Expected Stats (Find Undervalued Players)

"Show me batters whose expected stats were way higher than their actual stats in 2024"

statcast_batter_expected_stats(year=2024)

"What are Aaron Judge's expected stats vs actual in 2025?"

statcast_batter_expected_stats(year=2025, player_name="Aaron Judge")

Exit Velocity Leaders

"Who hit the ball hardest in 2024?"

statcast_batter_exitvelo_barrels(year=2024)

Pitcher Arsenal

"What pitches does Spencer Strider throw and how effective are they?"

statcast_pitcher_pitch_arsenal(year=2024)
statcast_pitcher_arsenal_stats(year=2024)

Sprint Speed

"Who are the fastest players in baseball?"

sprint_speed_leaderboard(year=2024)

Standings

"Show me the 2024 MLB standings"

team_standings(season=2024)

Percentile ranks & defense

"What are Aaron Judge's Statcast percentile ranks in 2024?"

batter_percentile_ranks(year=2024, player_name="Aaron Judge")

"Who were the best defensive shortstops by OAA in 2024?"

outs_above_average(year=2024, position="SS")

Hot streaks (date ranges)

"Who hit the best from July 1 to July 31, 2024?"

batting_stats_date_range(start_date="2024-07-01", end_date="2024-07-31")

Data Sources

All data is sourced from:

• Baseball Savant — Statcast pitch-level and leaderboard data (2008+)

• FanGraphs — Season-level batting and pitching statistics

• Baseball Reference — Player identification, daily stat ranges, and cross-references

Reference Guide

For detailed tool-by-tool documentation, row limits, parameters, and usage patterns, see REFERENCE.md.

Social / sharing: Short descriptions and hashtag ideas for posts are in TOOLS_SUMMARY.md.

Notes

• Date ranges: Statcast data is available from 2008 onward. Some metrics (exit velocity, launch angle) are only available from 2015+.

• Query speed: Shorter date ranges return faster. For pitch-level data, keep ranges to 1-5 days when possible.

• Rate limits: Baseball Savant limits individual requests to ~30,000 rows. The server handles splitting larger queries automatically.

• Markdown row display: Each tool’s markdown table is capped by max_output_rows (defaults vary; hard maximum 5000 per limits.py) so responses stay bounded in chat clients.

• Player names: Tools accept names like "Mike Trout", "Trout, Mike", or "Shohei Ohtani". The server resolves names to MLB IDs automatically.

Development

# Clone the repo
git clone https://github.com/YOUR_USERNAME/statcast-mcp.git
cd statcast-mcp

# Create a virtual environment and install in editable mode
uv venv
uv pip install -e ".[dev]"

# Run the server locally
statcast-mcp

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector statcast-mcp

# Smoke-test all 46 tools (needs network; ~2024 fixtures)
PYTHONPATH=src python scripts/verify_tools.py

Contributing

Contributions are welcome! Some ideas:

• Add more tools (game scores, team batting/pitching, historical data)

• Improve player name resolution

• Add data caching for faster repeated queries

• Create prompt templates for common analyses

License

MIT