baseball-mcp

Linell/baseball-mcp

3.2

If you are the rightful owner of baseball-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for retrieving baseball information using the pybaseball library.

Tools

  1. get_player_stats

    Season or career stats for a single player

  2. get_team_stats

    Team-level splits by season

  3. get_schedule

    Games for a team in a date range

  4. get_statcast

    Pitch-by-pitch Statcast data

  5. get_standings

    Division and league standings

  6. compare_players

    Side-by-side player comparison

  7. get_game_log

    Game-by-game logs for players/teams

  8. similarity_score

    Sabermetric similarity between players

  9. park_factors

    Ballpark factors affecting stats

  10. list_team_abbreviations

    List valid team abbreviations

Baseball MCP Server

A Model Context Protocol (MCP) server for retrieving baseball information using the pybaseball library.

Baseball Reference, Baseball Savant, and FanGraphs so you don't have to.

Overview

This MCP server provides access to comprehensive baseball data through a standardized interface. It leverages the pybaseball library to fetch statistics, game information, and player data from various baseball databases.

The primary purpose is to make baseball analysis easy, with a particular focus on fantasy baseball.

Features

  • Player statistics retrieval
  • Team performance data
  • Game schedules and results
  • Statcast pitch-by-pitch data
  • League standings
  • Player comparison tools
  • Game logs for players and teams
  • Sabermetric similarity scoring
  • Ballpark factor analysis
  • MCP Resources for comprehensive data packages
  • SQLite caching for performance
  • Both STDIO and HTTP server transports

Installation

Prerequisites

  • Python 3.8 or higher
  • pip package manager

Setup

  1. Clone the repository:
git clone https://github.com/Linell/baseball-mcp.git
cd baseball-mcp
  1. Install the package:
pip install -e .

Or for development:

pip install -e ".[dev]"

Usage

Running the Server

Run the STDIO server (default):

baseball-mcp run

Run the HTTP server on port 3000:

baseball-mcp http --port 3000

Reset the on-disk cache:

baseball-mcp cache-reset --confirm

Check server health:

baseball-mcp health

Available Tools

ToolSummaryParameters
get_player_statsSeason or career stats for a single playerplayer_name (required), year (optional)
get_team_statsTeam-level splits by seasonteam (required), year (required)
get_scheduleGames for a team in a date rangeteam (required), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD)
get_statcastPitch-by-pitch Statcast datastart_date (YYYY-MM-DD), end_date (YYYY-MM-DD), player_id (optional), statcast_type (optional), format_type (optional)
get_standingsDivision and league standingsyear (required), date (optional)
compare_playersSide-by-side player comparisonplayers (list), year (required), metric (optional)
get_game_logGame-by-game logs for players/teamsentity (required), entity_type (optional), start_date (YYYY-MM-DD), end_date (YYYY-MM-DD)
similarity_scoreSabermetric similarity between playersplayer_a (required), player_b (required), year (required), metric_set (optional)
park_factorsBallpark factors affecting statsyear (required), venue (optional)
list_team_abbreviationsList valid team abbreviationsNone

Example Usage

  • "Get Mike Trout's 2023 stats" → uses get_player_stats
  • "Show me the Yankees' 2024 team statistics" → uses get_team_stats
  • "What's the Padres' schedule for March 2025?" → uses get_schedule
  • "Get Statcast data for Aaron Judge from June 1-7, 2024" → uses get_statcast
  • "Show me the 2024 AL East standings" → uses get_standings
  • "Compare Mike Trout and Aaron Judge's 2024 stats" → uses compare_players

Team Abbreviations

The server supports various team abbreviations for convenience:

  • San Diego Padres: SD or SDP
  • San Francisco Giants: SF or SFG
  • Tampa Bay Rays: TB or TBR
  • Kansas City Royals: KC or KCR
  • Chicago White Sox: CWS or CHW
  • Washington Nationals: WSH or WSN

For a complete list, use the list_team_abbreviations tool.

Deployment

This MCP server can be deployed to services like Smithery or any container platform.

Configuration

The server supports the following configuration options via query parameters:

  • cache_reset (boolean): Whether to reset the cache on startup
  • log_level (string): Logging level (DEBUG, INFO, WARNING, ERROR)
  • max_results (integer): Maximum number of results to return (1-1000)

Example: GET /mcp?cache_reset=false&log_level=INFO&max_results=100

Local Testing

Test the HTTP server locally:

# Start the server
baseball-mcp http --port 3000

# Test the MCP endpoint
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# Check health
curl http://localhost:3000/health

Development

Setting up Development Environment

  1. Clone the repository
  2. Install development dependencies:
pip install -e ".[dev]"
  1. Install pre-commit hooks:
pre-commit install

Running Tests

pytest

Code Quality

This project uses several tools to maintain code quality:

  • Black: Code formatting
  • Ruff: Linting and code analysis
  • MyPy: Type checking
  • Pre-commit: Git hooks for code quality

Run all checks:

black src tests
ruff check src tests
mypy src

Configuration

Cache

The server uses SQLite for caching baseball data to improve performance and reduce API calls.

  • Default location: ~/.config/baseball-mcp/baseball.db
  • Management: Data is automatically cached when first requested
  • Reset: Use baseball-mcp cache-reset --confirm to clear all cached data

Server Modes

  • STDIO Mode (default): Runs as an MCP server for local AI clients
  • HTTP Mode: Runs as an HTTP server for remote access (baseball-mcp http --port 8000)

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Run the test suite
  6. Submit a pull request

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Resources