MLB Stats MCP Server

MLB Stats MCP Server

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:

uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\Scripts\activate  # On Windows

3. Install dependencies:

uv pip install -e .

Installing via Smithery

To install MLB Stats Server for Claude Desktop automatically via Smithery:

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

Running Tests

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

uv run pytest -v

Tests verify all MLB StatsAPI tools work correctly with the MCP protocol, establishing connections, making API calls, and processing responses.

Environment Variables

The project uses environment variables stored in .env to configure settings.

Use ANTHROPIC_API_KEY to enable MCP Server.

Logging Configuration

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 stderr)

Logs go to stderr rather than stdout on purpose: under the stdio transport, stdout carries the JSON-RPC stream and anything else printed there corrupts it.

HTTP Transport

Run the server over HTTP with python -m mlb_stats_mcp.server --http, which listens on $PORT (default 8081) and serves MCP at /mcp.

By default the server accepts any Host and any Origin, so a remote deployment works out of the box. To restrict it, set either variable to a comma-separated list:

• MLB_STATS_ALLOWED_HOSTS - Host header values to accept. Setting this turns on DNS rebinding protection; requests for any other host are rejected with 421. Entries may end in :* to allow any port, e.g. localhost:*.
• MLB_STATS_ALLOWED_ORIGINS - Origin values to accept, used both for CORS and, when MLB_STATS_ALLOWED_HOSTS is set, to reject other origins with 403. Requests without an Origin header are always allowed.

Set both when locking down a deployment; naming hosts alone rejects every browser-based client.

Claude Desktop Integration

To connect this MCP server to Claude Desktop, add a configuration to your claude_desktop_config.json file. Here's a template configuration:

"mcp-baseball-stats": {
  "command": "{PATH_TO_UV}",
  "args": [
    "--directory",
    "{PROJECT_DIRECTORY}",
    "run",
    "python",
    "-m",
    "mlb_stats_mcp.server"
  ],
  "env": {
    "MLB_STATS_LOG_FILE": "{LOG_FILE_PATH}",
    "MLB_STATS_LOG_LEVEL": "DEBUG"
  }
}

Replace the following placeholders:

• {PATH_TO_UV}: Path to your uv installation (e.g., ~/.local/bin/uv)
• {PROJECT_DIRECTORY}: Path to your project directory
• {LOG_FILE_PATH}: Path where you want to store the log file

Technologies Used

• mcp[cli] - Machine-Learning Chat Protocol for tool definition
• mlb-statsapi - Python wrapper for the MLB Stats API
• httpx - HTTP client for making API requests
• pytest and pytest-asyncio - Test frameworks
• uv - Fast Python package manager and installer

Linting

This project uses Ruff for linting and code formatting, with pre-commit hooks to ensure code quality.

Setup Pre-commit Hooks

1. Install pre-commit:

pip install pre-commit

2. Initialize pre-commit hooks:

pre-commit install

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

pre-commit run --all-files

Linting Configuration

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

CI Integration

GitHub Actions workflows automatically run tests, linting, and pre-commit checks on all pull requests and pushes to the main branch.