What is Mlb Mcp

mlb-mcp is an MCP server designed for advanced baseball analytics, providing access to MLB statistics data through various APIs, including the MLB Stats API, statcast, fangraphs, and baseball reference.

Use cases

Use cases for mlb-mcp include building analytics dashboards for baseball teams, creating data visualizations for player performance analysis, and developing applications that require real-time access to MLB statistics.

How to use

To use mlb-mcp, first install the necessary dependencies and set up a virtual environment. Then, run the server and access the structured API for baseball statistics using MCP-compatible clients.

Key features

Key features of mlb-mcp include structured API access to MLB statistics, integration with multiple data sources (statcast, fangraphs, baseball reference), and tools for data visualization using matplotlib.

Where to use

mlb-mcp can be used in fields such as sports analytics, data science, and software development, particularly for applications focusing on baseball statistics and analytics.

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 .

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

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:

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.