MLB Stats Server is an MCP server that provides structured access to Major League Baseball statistics, enabling AI assistants to query and visualize detailed baseball analytics. Key features of MLB Stats Server: - Access to official MLB Stats API data for real-time and historical game statistics - Statcast data integration for advanced player and pitch tracking metrics - Fangraphs statistics for sabermetrics and analytical baseball insights - Baseball Reference data for comprehensive historical player and team records - Matplotlib-based visualization generation that returns plots as base64-encoded images for seamless display in chat clients

MLB Stats MCP Server

[](https://github.com/etweisberg/baseball/mcp-baseball-stats/workflows/test.yml) [](https://github.com/etweisberg/mcp-baseball-stats/actions/workflows/pre-commit.yml) [](https://smithery.ai/server/@etweisberg/mlb-mcp)

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

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:

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:

Technologies Used

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.