mlb-mcp

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# MLB Stats MCP Server

A Model Context Protocol (MCP) server that provides comprehensive MLB baseball statistics with video highlights through the [pybaseball](https://github.com/jldbc/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:

```json
{
  "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](https://smithery.ai) 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](https://smithery.ai)
3. Deploy directly from your repository

### Local Development

```bash
# 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):

```json
{
  "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](https://github.com/jldbc/pybaseball) and [FastMCP](https://github.com/jlowin/fastmcp)

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:

Create a new Railway project and connect your GitHub repository
Railway will auto-detect the Procfile and deploy automatically
Your MCP endpoint will be available at https://<your-railway-domain>/mcp
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

Fork this repository
Connect your GitHub account to Smithery
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