Pybaseball MCP Server

MLB Stats MCP Server

A Model Context Protocol (MCP) server that provides comprehensive MLB baseball statistics with video highlights through the pybaseball library.

Overview

This MCP server enables AI assistants to access real-time MLB statistics, historical data, and video highlights. It provides eight powerful tools for querying baseball data, from individual player performance to team statistics and advanced Statcast metrics.

Features

🎯 8 Core Tools

1. get_player_stats

Get detailed Statcast data for any MLB player with optional date filtering.

• Parameters:
  • name (required): Player name (e.g., "Mike Trout", "Ronald Acuña Jr.")
  • start_date (optional): Start date in YYYY-MM-DD format
  • end_date (optional): End date in YYYY-MM-DD format
• Returns: Player statistics including hits, home runs, exit velocity, launch angle, and barrel rate

2. player_statcast

Get comprehensive Statcast data for a specific player with advanced pitch-type and result filtering.

• Parameters:
  • player_name (required): Player name (e.g., "Aaron Judge", "Mike Trout")
  • start_date (optional): Start date in YYYY-MM-DD format (defaults to current season)
  • end_date (optional): End date in YYYY-MM-DD format (defaults to current season)
  • pitch_type (optional): Filter by pitch type - 'FF' (4-seam), 'SL' (slider), 'CH' (changeup), 'CU' (curveball), 'SI' (sinker), 'FC' (cutter), 'FS' (splitter)
  • result_type (optional): Filter by result - 'home_run', 'hit', 'single', 'double', 'triple', 'batted_ball'
  • min_exit_velocity (optional): Minimum exit velocity in mph
  • min_distance (optional): Minimum distance in feet
• Returns: Player stats with overall metrics, breakdown by pitch type/result, and top 5 examples with video links
• Example Queries:
  • "How many fastballs has Aaron Judge hit for a home run?"
  • "What's Shohei Ohtani's average exit velocity on sliders?"
  • "Show me Mike Trout's stats against breaking balls this season"

3. get_team_stats

Retrieve comprehensive team batting or pitching statistics for any season.

• Parameters:
  • team (required): Team name or abbreviation (e.g., "Yankees", "NYY", "Red Sox")
  • year (required): Season year (1871-present)
  • stat_type (optional): "batting" (default) or "pitching"
• Returns: Complete team statistics for the specified season

4. get_leaderboard

Access statistical leaderboards for any MLB stat category.

• Parameters:
  • stat (required): Statistic abbreviation (e.g., "HR", "AVG", "ERA", "K")
  • season (required): Season year
  • leaderboard_type (optional): "batting" or "pitching"
  • limit (optional): Number of results (default: 10)
• Returns: Top players for the specified statistic

5. statcast_leaderboard

Query advanced Statcast data with filtering, sorting, and video highlight links.

• Parameters:
  • start_date (required): Start date in YYYY-MM-DD format
  • end_date (required): End date in YYYY-MM-DD format
  • result (optional): Filter by outcome (e.g., "home_run", "single", "double")
  • min_ev (optional): Minimum exit velocity filter
  • min_pitch_velo (optional): Minimum pitch velocity filter
  • pitch_type (optional): Filter by pitch type - 'FF' (4-seam), 'SL' (slider), 'CH' (changeup), 'CU' (curveball), 'SI' (sinker), 'FC' (cutter), 'FS' (splitter)
  • player_name (optional): Filter by batter name (e.g., "Aaron Judge", "Mike Trout")
  • sort_by (optional): Sort metric:
    • "exit_velocity" (default) - Hardest hit balls
    • "distance" - Longest hits
    • "launch_angle" - Optimal launch angles
    • "pitch_velocity" - Fastest pitches
    • "spin_rate" - Highest spin rates
    • "xba" - Highest expected batting average
    • "xwoba" - Highest expected weighted on-base average
    • "barrel" - Barrel rate (perfect contact)
  • limit (optional): Number of results (default: 10)
  • order (optional): Sort order - "desc" (default) or "asc"
  • group_by (optional): Group results by "team" for team-wide rankings
• Returns: Detailed play-by-play data with video links (or team aggregations when group_by="team")

6. team_season_stats

Get fast team season averages for Statcast metrics. Optimized for queries like "which team hits the ball hardest?".

• Parameters:
  • year (required): Season year (e.g., 2025)
  • stat (optional): Metric to analyze
    • "exit_velocity" (default) - Average exit velocity
    • "distance" - Average and max distance
    • "launch_angle" - Average launch angle
    • "barrel_rate" - Percentage of barrels (perfect contact)
    • "hard_hit_rate" - Percentage of balls hit 95+ mph
    • "sweet_spot_rate" - Percentage hit at optimal launch angles (8-32°)
  • min_result_type (optional): Filter by result type
    • "batted_ball" - All balls in play
    • "home_run" - Home runs only
    • "hit" - All hits (singles, doubles, triples, home runs)
• Returns: Team rankings with averages, counts, and other statistics
• Performance: Uses sampling strategy (every 7th day) and 24-hour caching for instant responses

7. team_pitching_stats

Get fast team pitching averages for Statcast metrics. Optimized for queries like "which team has the best pitching staff?".

• Parameters:
  • year (required): Season year (e.g., 2025)
  • stat (optional): Metric to analyze
    • "velocity" (default) - Average and max pitch velocity
    • "spin_rate" - Average and max spin rate
    • "movement" - Pitch break (horizontal, vertical, total)
    • "whiff_rate" - Swing-and-miss percentage
    • "chase_rate" - Swings at pitches outside the zone
    • "zone_rate" - Percentage of pitches in strike zone
    • "ground_ball_rate" - Ground balls per balls in play
    • "xera" - Expected ERA based on quality of contact
  • pitch_type (optional): Filter to specific pitch type
    • "FF" - 4-seam fastball
    • "SL" - Slider
    • "CH" - Changeup
    • "CU" - Curveball
    • "SI" - Sinker
    • "FC" - Cutter
    • "FS" - Splitter
• Returns: Team pitching rankings with averages, counts, and other statistics
• Performance: Uses sampling strategy (every 7th day) and 24-hour caching for instant responses

8. statcast_count

Count Statcast events matching specific criteria. Optimized for multi-year queries like "how many 475+ ft home runs since 2023?"

• Parameters:
  • start_date (required): Start date in YYYY-MM-DD format
  • end_date (required): End date in YYYY-MM-DD format
  • result_type (optional): Type to count - 'home_run' (default), 'hit', 'batted_ball', or specific like 'double'
  • player_name (optional): Filter by batter name (e.g., "Aaron Judge", "Mike Trout")
  • pitch_type (optional): Filter by pitch type - 'FF' (4-seam), 'SL' (slider), 'CH' (changeup), 'CU' (curveball), 'SI' (sinker), 'FC' (cutter), 'FS' (splitter)
  • min_distance (optional): Minimum distance in feet (e.g., 475)
  • max_distance (optional): Maximum distance in feet
  • min_exit_velocity (optional): Minimum exit velocity in mph
  • max_exit_velocity (optional): Maximum exit velocity in mph
• Returns: Total count, yearly breakdown, and top 5 examples with video links
• Performance:
  • Multi-year queries: Samples 3 days per month (~90x fewer API calls)
  • 6-12 months: Weekly sampling (~7x fewer API calls)
  • <6 months: Complete data with chunking
  • 24-hour caching for all queries

🎥 Video Highlights Integration

Every result from statcast_leaderboard includes detailed metrics and video access points:

{
  "rank": 1,
  "player": "Ronald Acuña Jr.",
  "date": "2024-07-20",
  "exit_velocity": 113.7,
  "launch_angle": 23.0,
  "distance": 456.0,
  "result": "home_run",
  "pitch_velocity": 95.2,
  "pitch_type": "FF",
  "spin_rate": 2450,
  "xba": 0.920,
  "xwoba": 1.823,
  "barrel": true,
  "description": "Ronald Acuña Jr. homers (13) on a fly ball to center field.",
  "video_links": {
    "game_highlights_url": "https://www.mlb.com/gameday/745890/video",
    "film_room_search": "https://www.mlb.com/video/search?q=Ronald+Acuna+Jr.+2024-07-20",
    "game_pk": "745890",
    "api_highlights_endpoint": "https://statsapi.mlb.com/api/v1/schedule?gamePk=745890&hydrate=game(content(highlights(highlights)))"
  }
}

🏟️ Smart Team Recognition

The server intelligently handles team names:

• Full names: "Orioles" → "BAL", "Red Sox" → "BOS"
• Cities: "Boston" → "BOS", "New York Yankees" → "NYY"
• Historical teams: "Expos" → "MON", "Indians" → "CLE"
• All 30 current MLB teams supported with common variations

📊 Team-Wide Rankings

New team aggregation feature for statcast_leaderboard:

• Group results by team to see team-wide performance
• Calculates averages, maximums, and counts for each metric
• Perfect for questions like "Which team hits the hardest home runs?"
• Returns comprehensive team statistics including barrel counts and expected metrics

Installation

Deploy on Railway (Recommended for Smithery)

Deploy to Railway for a hosted HTTP MCP endpoint that Smithery can connect to:

1. Create a new Railway project and connect your GitHub repository
2. Railway will auto-detect the Procfile and deploy automatically
3. Your MCP endpoint will be available at https://<your-railway-domain>/mcp
4. Connect this URL to Smithery for distribution

Manual Start Command (if needed): If Railway doesn't auto-detect the Procfile, set this Start Command in Railway Settings:

uv run fastmcp run src/mlb_mcp/server.py:mcp --transport http --host 0.0.0.0 --port $PORT

Deploy on Smithery Direct

1. Fork this repository
2. Connect your GitHub account to Smithery
3. Deploy directly from your repository

Local Development

# Clone the repository
git clone https://github.com/yourusername/mlb_mcp.git
cd mlb_mcp

# Install dependencies with uv
uv sync

# Run the server (stdio mode for local testing)
uv run python -m mlb_mcp.server

# Or run with HTTP transport for local HTTP testing
MCP_TRANSPORT=http MCP_PORT=8000 uv run python -m mlb_mcp.server

Claude Desktop Configuration

Add to your Claude Desktop configuration (uses stdio transport):

{
  "mcpServers": {
    "mlb-stats": {
      "command": "uv",
      "args": ["run", "python", "-m", "mlb_mcp.server"],
      "cwd": "/path/to/mlb_mcp"
    }
  }
}

Usage Examples

Player-Specific Queries (NEW!)

How many fastballs has Aaron Judge hit for a home run?

Query: "How many fastballs has Aaron Judge hit for a home run this season?"
Tool: player_statcast("Aaron Judge", "2024-04-01", "2024-10-31", "FF", "home_run")
OR
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", player_name="Aaron Judge", pitch_type="FF")

What's a player's performance on specific pitch types?

Query: "Show me Shohei Ohtani's stats against sliders this season"
Tool: player_statcast("Shohei Ohtani", "2024-04-01", "2024-10-31", "SL")

Player's hardest hit balls on specific pitch types

Query: "Show Aaron Judge's hardest hit balls on fastballs"
Tool: statcast_leaderboard("2024-04-01", "2024-10-31", player_name="Aaron Judge", pitch_type="FF", sort_by="exit_velocity", limit=10)

Find the Longest Home Runs

Query: "Show me the longest home runs from yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", "home_run", None, None, "distance", 10)

Hardest Hit Balls on Fast Pitches

Query: "What were the hardest hit balls on 99+ mph pitches last week?"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, 0, 99.0, "exit_velocity", 10)

Fastest Pitches Thrown

Query: "Show me the fastest pitches thrown yesterday"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10)

Highest Spin Rate Pitches

Query: "What pitches had the highest spin rate today?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "spin_rate", 10)

Best Quality Contact (Barrels)

Query: "Show me the best quality contact this week"
Tool: statcast_leaderboard("2024-07-14", "2024-07-20", None, None, None, "barrel", 10)

Player Season Stats

Query: "Get Mike Trout's stats for this season"
Tool: get_player_stats("Mike Trout", "2024-04-01", "2024-10-01")

Team Performance

Query: "How are the Red Sox doing this year?"
Tool: get_team_stats("Red Sox", 2024, "batting")

League Leaders

Query: "Who's leading the league in home runs?"
Tool: get_leaderboard("HR", 2024, "batting", 10)

Team-Wide Rankings (statcast_leaderboard)

Query: "Which team has the hardest hit home runs this season?"
Tool: statcast_leaderboard("2024-04-01", "2024-10-01", "home_run", None, None, "exit_velocity", 10, "desc", "team")

Query: "Show me teams with the longest average home run distance this month"
Tool: statcast_leaderboard("2024-07-01", "2024-07-31", "home_run", None, None, "distance", 10, "desc", "team")

Query: "Which teams have the highest average pitch velocity?"
Tool: statcast_leaderboard("2024-07-20", "2024-07-20", None, None, None, "pitch_velocity", 10, "desc", "team")

Team Season Averages (team_season_stats)

Query: "What team averages the hardest hit balls in 2025?"
Tool: team_season_stats(2025, "exit_velocity")

Query: "Which team has the highest barrel rate this season?"
Tool: team_season_stats(2025, "barrel_rate")

Query: "Show me teams with the highest hard-hit rate on home runs only"
Tool: team_season_stats(2025, "hard_hit_rate", "home_run")

Query: "What team hits the ball the farthest on average?"
Tool: team_season_stats(2025, "distance")

Team Pitching Analysis (team_pitching_stats)

Query: "Which team throws the hardest in 2025?"
Tool: team_pitching_stats(2025, "velocity")

Query: "What team has the best slider spin rate?"
Tool: team_pitching_stats(2025, "spin_rate", "SL")

Query: "Which pitching staff gets the most swings and misses?"
Tool: team_pitching_stats(2025, "whiff_rate")

Query: "Show me teams with the highest ground ball rate"
Tool: team_pitching_stats(2025, "ground_ball_rate")

Query: "Which team has the lowest expected ERA based on contact quality?"
Tool: team_pitching_stats(2025, "xera")

Counting Queries (statcast_count)

Query: "How many home runs hit over 475 ft have been hit since 2023?"
Tool: statcast_count("2023-01-01", "2025-12-31", "home_run", 475)

Query: "Count all 110+ mph batted balls this season"
Tool: statcast_count("2025-04-01", "2025-10-31", "batted_ball", None, 110)

Query: "How many home runs between 400-450 feet were hit last year?"
Tool: statcast_count("2024-04-01", "2024-10-31", "home_run", 400, None, 450)

Query: "Total hits with exit velocity over 100 mph since 2022"
Tool: statcast_count("2022-01-01", "2025-12-31", "hit", None, 100)

Technical Details

Architecture

• Transport: stdio (local) or HTTP (Railway/hosted) - auto-detected via PORT env var
• Framework: FastMCP for protocol implementation
• Data Source: pybaseball library (MLB official data)
• Language: Python 3.11+
• Deployment: Railway (HTTP) or Smithery (containerized)

Performance Optimizations

• Query Chunking: Automatically splits large date ranges into 5-day chunks to handle Baseball Savant's 30,000 row limit
• Response Caching: 15-minute cache for repeated queries, 24-hour cache for team season stats
• Vectorized Operations: Uses NumPy for efficient team identification instead of slower pandas apply() operations
• Sampling Strategy:
  • team_season_stats and team_pitching_stats: Every 7th day sampling
  • statcast_count: Adaptive sampling (3 days/month for multi-year, weekly for 6-12 months)
• Specialized Tools: Dedicated tools for common aggregate queries that would timeout with full data:
  • team_season_stats for batting metrics
  • team_pitching_stats for pitching metrics
  • statcast_count for counting queries across multiple years
• Lazy Loading: Heavy dependencies (pandas, numpy, pybaseball) loaded only when needed for fast startup
• Efficient Filtering: Applies filters sequentially to minimize data processing overhead

Key Features

• Error Handling: Comprehensive error messages for common issues
• Type Safety: Proper type conversion for JSON serialization
• Video Integration: Automatic video highlight links for all plays and team top performances
• Smart Team Lookup: Handles full names, abbreviations, cities, and historical teams

File Structure

mlb_mcp/
├── src/
│   └── mlb_mcp/
│       ├── __init__.py    # Package exports
│       └── server.py      # Main MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── smithery.yaml          # Smithery deployment configuration
├── Procfile               # Railway start command
└── README.md              # This file

Requirements

• Python 3.11 or higher
• Internet connection for MLB data access
• Smithery account for deployment (optional)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project uses publicly available MLB data through the pybaseball library. All MLB data is property of MLB Advanced Media.

---

Built with pybaseball and FastMCP