MLB Stats MCP Server

SSE

by etweisberg

28 372 downloads Not rated yet

GitHub Website

Other

About

MCP server for advanced baseball analytics (statcast, fangraphs, baseball reference, mlb stats API)

Details

Transport: SSE

Explore

- Combines MLB Stats API, Statcast, FanGraphs, and Baseball Reference data.
- Generates matplotlib plots returned as base64-encoded images.
- Configurable logging via environment variables (MLB_STATS_LOG_LEVEL, MLB_STATS_LOG_FILE).
- Comprehensive test suite using pytest and pytest-asyncio.
- Linting and code formatting enforced by Ruff and pre-commit hooks.
- Option to install automatically via Smithery for Claude Desktop.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name MLB Stats MCP Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

From the repository

1. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create and activate a virtual environment:

uv venv source .venv/bin/activate # On Unix/macOS To install MLB Stats Server for Claude Desktop automatically via Smithery:

bash
npx -y @smithery/cli install @etweisberg/mlb-mcp --client claude

The project includes comprehensive pytest tests for the MCP server functionality:

bash
uv run pytest -v

Tests verify all MLB StatsAPI tools work correctly with the MCP protocol, establishing connections, making API calls, and processing responses. The project uses environment variables stored in .env to configure settings. Use ANTHROPIC_API_KEY to enable MCP Server. The MLB Stats MCP Server supports configurable logging via environment variables: - MLB_STATS_LOG_LEVEL - Sets the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) - MLB_STATS_LOG_FILE - Path to log file (if not set, logs to stdout) 1. Install pre-commit:

bash
pip install pre-commit

2. Initialize pre-commit hooks:

bash
pre-commit install

Now, the linting checks will run automatically whenever you commit code. You can also run them manually:

bash
pre-commit run --all-files
``

Linting rules are configured in the pyproject.toml file under the [tool.ruff]` section. The project follows PEP 8 style guidelines with some customizations.

`get_stats`

`get_schedule`

Get list of games for a given date/range and/or team/opponent.

`get_player_stats`

Returns a list of current season or career stat data for a given player.

`get_standings`

Returns a dict of standings data for a given league/division and season.

`get_team_leaders`

Returns a python list of stat leader data for a given team

`lookup_player`

Get data about players based on first, last, or full name.

`get_boxscore`

Get a formatted boxscore for a given game.

`get_team_roster`

Get the roster for a given team.

`get_game_pace`

Returns data about pace of game for a given season (back to 1999).

`get_meta`

Get available values from StatsAPI for use in other queries, or look up descriptions for values found in API results. For example, to get a list of leader categories to use when calling team_leaders(): statsapi.meta('leagueLeaderTypes')

`get_available_endpoints`

Get MLB StatsAPI endpoints directly

`get_notes`

Get additional notes on an endpoint

`get_game_scoring_play_data`

Returns a dictionary of scoring plays for a given game containing 3 keys: * home - home team data * away - away team data * plays - sorted list of scoring play data

`get_last_game`

Get the gamePk (game_id) for the given team's most recent completed game.

`get_league_leader_data`

Returns a list of stat leaders overall or for a given league (103=AL, 104=NL).

`get_linescore`

Get formatted linescore data for a specific MLB game.

`get_next_game`

Get the game ID for a team's next scheduled game.

`get_game_highlight_data`

Returns a list of highlight data for a given game.

`get_statcast_data`

Pulls statcast play-level data from Baseball Savant for a given date range. INPUTS: start_dt: YYYY-MM-DD : the first date for which you want statcast data end_dt: YYYY-MM-DD : the last date for which you want statcast data team: optional (defaults to None) : city abbreviation of the team you want data for (e.g. SEA or BOS) verbose: bool (defaults to True) : whether to print updates on query progress parallel: bool (defaults to True) : whether t…

`get_statcast_batter_data`

Pulls statcast pitch-level data from Baseball Savant for a given batter. ARGUMENTS start_dt : YYYY-MM-DD : the first date for which you want a player's statcast data end_dt : YYYY-MM-DD : the final date for which you want data player_id : INT : the player's MLBAM ID. Find this by via the get_playerid_lookup tool, finding the correct player, and selecting their key_mlbam. start_row: optional (defaults to None)…

`get_statcast_pitcher_data`

Pulls statcast pitch-level data from Baseball Savant for a given pitcher. ARGUMENTS start_dt : YYYY-MM-DD : the first date for which you want a player's statcast data end_dt : YYYY-MM-DD : the final date for which you want data player_id : INT : the player's MLBAM ID. Find this by calling pthe get_playerid_lookup tool, finding the correct player, and selecting their key_mlbam. start_row: optional (defaults to…

`get_statcast_batter_exitvelo_barrels`

Retrieves batted ball data for all batters in a given year. ARGUMENTS year: The year for which you wish to retrieve batted ball data. Format: YYYY. minBBE: The minimum number of batted ball events for each player. If a player falls below this threshold, they will be excluded from the results. If no value is specified, only qualified batters will be returned. start_row: optional (defaults to None) : starting row index…

`get_statcast_pitcher_exitvelo_barrels`

Retrieves batted ball against data for all qualified pitchers in a given year. ARGUMENTS year: The year for which you wish to retrieve batted ball against data. Format: YYYY. minBBE: The minimum number of batted ball against events for each pitcher. If a player falls below this threshold, they will be excluded from the results. If no value is specified, only qualified pitchers will be returned. start_row: optional (defaults to N…

`get_statcast_batter_expected_stats`

Retrieves expected stats based on quality of batted ball contact in a given year. ARGUMENTS year: The year for which you wish to retrieve expected stats data. Format: YYYY. minPA: The minimum number of plate appearances for each player. If a player falls below this threshold, they will be excluded from the results. If no value is specified, only qualified batters will be returned. start_row: optional (defaults to None) : startin…

`get_statcast_pitcher_expected_stats`

Retrieves expected stats based on quality of batted ball contact against in a given year. ARGUMENTS year: The year for which you wish to retrieve expected stats data. Format: YYYY. minPA: The minimum number of plate appearances against for each pitcher. If a player falls below this threshold, they will be excluded from the results. If no value is specified, only qualified pitchers will be returned. start_row: optiona…

`get_statcast_batter_percentile_ranks`

Retrieves percentile ranks for batters in a given year. ARGUMENTS year: The year for which you wish to retrieve percentile data. Format: YYYY. start_row: optional (defaults to None) : starting row index for truncating large results (0-based, inclusive) end_row: optional (defaults to None) : ending row index for truncating large results (0-based, exclusive) Use start_row and end_row to limit response size when dealing with large datasets.

`get_statcast_pitcher_percentile_ranks`

Retrieves percentile ranks for each player in a given year, including batters with 2.1 PA per team game and 1.25 for pitchers. It includes percentiles on expected stats, batted ball data, and spin rates, among others. ARGUMENTS year: The year for which you wish to retrieve percentile data. Format: YYYY. start_row: optional (defaults to None) : starting row index for truncating large results (0-based, inclusive) end_row: optional (defaults t…

`get_statcast_batter_pitch_arsenal`

Retrieves outcome data for batters split by the pitch type in a given year. ARGUMENTS year: The year for which you wish to retrieve pitch arsenal data. Format: YYYY. minPA: The minimum number of plate appearances for each player. If a player falls below this threshold, they will be excluded from the results. If no value is specified, the default number of plate appearances is 25. start_row: optional (defaults to None) : …

`get_statcast_pitcher_pitch_arsenal`

Retrieves high level stats on each pitcher's arsenal in a given year. ARGUMENTS year: The year for which you wish to retrieve expected stats data. Format: YYYY. minP: The minimum number of pitches thrown. If a player falls below this threshold, they will be excluded from the results. If no value is specified, only qualified pitchers will be returned. arsenal_type: The type of stat to retrieve for the pitchers' arsenals. …

`get_statcast_single_game`

Pulls statcast play-level data from Baseball Savant for a single game, identified by its MLB game ID (game_pk in statcast data) INPUTS: game_pk : 6-digit integer MLB game ID to retrieve start_row: optional (defaults to None) : starting row index for truncating large results (0-based, inclusive) end_row: optional (defaults to None) : ending row index for truncating large results (0-based, exclusive) Use start_row and end_row to limit response size when…

`create_strike_zone_plot`

Produces a pitches overlaid on a strike zone using StatCast data Args: data: (pandas.DataFrame) StatCast pandas.DataFrame of StatCast pitcher data title: (str), default = '' Optional: Title of plot colorby: (str), default = 'pitch_type' Optional: Which category to color the mark with. 'pitch_type', 'pitcher', 'description' or a column within data legend_title: (str), default = based on colorby Opt…

`create_spraychart_plot`

Produces a spraychart using statcast data overlayed on specified stadium Args: data: (pandas.DataFrame) StatCast pandas.DataFrame of StatCast batter data team_stadium: (str) Team whose stadium the hits will be overlaid on title: (str), default = '' Optional: Title of plot size: (int), default = 100 Optional: Size of hit circles on plot colorby: (str), default = 'events' Optional: Which ca…

`create_bb_profile_plot`

Plots a given StatCast parameter split by bb_type Args: df: (pandas.DataFrame) pandas.DataFrame of StatCast batter data (retrieved through statcast, statcast_batter, etc) parameter: (str), default = 'launch_angle' Optional: Parameter to plot

`create_teams_plot`

Plots a scatter plot with each MLB team Args: data: (pandas.DataFrame) pandas.DataFrame of Fangraphs team data (retrieved through team_batting or team_pitching) x_axis: (str) Stat name to be plotted as the x_axis of the chart y_axis: (str) Stat name to be plotted as the y_axis of the chart title: (str), default = None Optional: Title of the plot

`get_pitching_stats_bref`

Get all pitching stats for a set season. If no argument is supplied, gives stats for current season to date.

`get_pitching_stats_range`

Get all pitching stats for a set time range. This can be the past week, the month of August, anything. Just supply the start and end date in YYYY-MM-DD format.

`get_pitching_stats`

Get season-level pitching data from FanGraphs. Args: start_season: First season to retrieve data from end_season: Final season to retrieve data from. If None, returns only start_season. league: Either "all", "nl", "al", or "mnl" qual: Minimum number of plate appearances to be included ind: 1 for individual season level, 0 for aggregate data Returns: Dictionary containing pitching stats from FanGraphs

`get_playerid_lookup`

Lookup playerIDs (MLB AM, bbref, retrosheet, FG) for a given player Args: last (str, required): Player's last name. first (str, optional): Player's first name. Defaults to None. fuzzy (bool, optional): In case of typos, returns players with names close to input. Defaults to False. Returns: pd.DataFrame: DataFrame of playerIDs, name, years played

`reverse_lookup_player`

Retrieve a table of player information given a list of player ids :param player_ids: list of player ids :type player_ids: list :param key_type: name of the key type being looked up (one of "mlbam", "retro", "bbref", or "fangraphs") :type key_type: str :rtype: :class:`pandas.core.frame.DataFrame`

`get_schedule_and_record`

Retrieve a team's game-level results for a given season, including win/loss/tie result, score, attendance, and winning/losing/saving pitcher. If the season is incomplete, it will provide scheduling information for future games. ARGUMENTS season: Integer. The season for which you want a team's record data. team: String. The abbreviation of the team for which you are requesting data (e.g. "PHI", "BOS", "LAD").

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "mlb stats mcp server": {
            "mlb-mcp": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

McpServers

{
    "mlb-mcp": {
        "command": "uv",
        "args": [
            "venv"
        ]
    }
}

A Python project that creates a Model Context Protocol (MCP) server for accessing MLB statistics data through the MLB Stats API and pybaseball library for statcast, fangraphs, and baseball reference statistics. This server provides structured API access to baseball statistics that can be used with MCP-compatible clients.

Project Structure

- mlb_stats_mcp/ - Main package directory
- server.py - Core MCP server implementation
- tools/ - MCP tool implementations
- mlb_statsapi_tools.py - MLB StatsAPI tool definitions
- statcast_tools.py - Statcast data tool definitions
- pybaseball_plotting_tools.py - Additional pybaseball tools provided for generating matplotlib plots and returning base64 encoded images
- pybaseball_supp_tools.py - Supplemental pybaseball functions for interfacing with fangraphs, baseball reference, and other data sources
- utils/ - Utility modules
- logging_config.py - Logging configuration
- images.py - functions related to handling plot images
- tests/ - Test suite for verifying server functionality
- pyproject.toml - Project configuration and dependencies
- .pre-commit-config.yaml - Pre-commit hooks configuration
- .github/ - GitHub Actions workflows

Tools

Setup

1. Install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Create and activate a virtual environment:

```bash
uv venv
source .venv/bin/activate # On Unix/macOS

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

get_stats

get_schedule

get_player_stats

get_standings

get_team_leaders

lookup_player

get_boxscore

get_team_roster

get_game_pace

get_meta

get_available_endpoints

get_notes

get_game_scoring_play_data

get_last_game

get_league_leader_data

get_linescore

get_next_game

get_game_highlight_data

get_statcast_data

get_statcast_batter_data

get_statcast_pitcher_data

get_statcast_batter_exitvelo_barrels

get_statcast_pitcher_exitvelo_barrels

get_statcast_batter_expected_stats

get_statcast_pitcher_expected_stats

get_statcast_batter_percentile_ranks

get_statcast_pitcher_percentile_ranks

get_statcast_batter_pitch_arsenal

get_statcast_pitcher_pitch_arsenal

get_statcast_single_game

create_strike_zone_plot

create_spraychart_plot

create_bb_profile_plot

create_teams_plot

get_pitching_stats_bref

get_pitching_stats_range

get_pitching_stats

get_playerid_lookup

reverse_lookup_player

get_schedule_and_record

Claude Desktop / Cursor

McpServers

Project Structure

Tools

Setup

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

`get_stats`

`get_schedule`

`get_player_stats`

`get_standings`

`get_team_leaders`

`lookup_player`

`get_boxscore`

`get_team_roster`

`get_game_pace`

`get_meta`

`get_available_endpoints`

`get_notes`

`get_game_scoring_play_data`

`get_last_game`

`get_league_leader_data`

`get_linescore`

`get_next_game`

`get_game_highlight_data`

`get_statcast_data`

`get_statcast_batter_data`

`get_statcast_pitcher_data`

`get_statcast_batter_exitvelo_barrels`

`get_statcast_pitcher_exitvelo_barrels`

`get_statcast_batter_expected_stats`

`get_statcast_pitcher_expected_stats`

`get_statcast_batter_percentile_ranks`

`get_statcast_pitcher_percentile_ranks`

`get_statcast_batter_pitch_arsenal`

`get_statcast_pitcher_pitch_arsenal`

`get_statcast_single_game`

`create_strike_zone_plot`

`create_spraychart_plot`

`create_bb_profile_plot`

`create_teams_plot`

`get_pitching_stats_bref`

`get_pitching_stats_range`

`get_pitching_stats`

`get_playerid_lookup`

`reverse_lookup_player`

`get_schedule_and_record`