mlb

This MLB Stats MCP Server provides access to MLB statistics by leveraging the MLB Stats API and pybaseball tools through an MCP-compatible interface. It exposes a set of stat-focused tools (e.g., MLB StatsAPI lookups, Statcast data, and pybaseball-derived plots and utilities) that clients can query via MCP protocols to retrieve structured baseball data, run analyses, or generate visuals. You can connect to the MCP server with any MCP client (such as Claude Desktop or custom tooling) and request tool calls by name, passing parameters like player IDs, teams, seasons, or date ranges; responses will be returned in a consistent structured format suitable for downstream consumption.

To use the server, start the Python module as described in the installation instructions. Once running, you can invoke the available tools through MCP tool calls. For example, you might retrieve Statcast data for a specific year, fetch player statistics from MLB Stats API, or generate pybaseball-derived plots that return images encoded in base64 for easy embedding in clients. The environment is configurable via the provided environment variables for logging and API keys, and you can adjust the verbosity of logs to help with debugging during development or integration.

Prerequisites:

• Python 3.8+ installed
• uv (Python package manager) or a virtual environment setup
• Access to the project repository (clone or download the code)

Install and run locally (using uv):

1. Create and activate a virtual environment (optional but recommended):

   • On Unix/macOS: uv venv source .venv/bin/activate
   • On Windows: uv venv .venv\Scripts\activate

2. Install the package in editable mode from the repository root: uv pip install -e .

3. Install additional dependencies and set up environment as needed (examples):

   • Create a .env file or export variables directly (example shown below)

4. Run the MCP server using uv (as shown in the README example): uv run python -m mlb_stats_mcp.server

Alternative installation via Smithery (for Claude Desktop integration):

• Use Smithery CLI to install the server package for a client, e.g.: npx -y @smithery/cli install @etweisberg/mlb-mcp --client claude

Note: Ensure MLB_STATS_LOG_LEVEL and MLB_STATS_LOG_FILE are configured if you want file-based logging. You may also need to provide an API key for anthropic-based features via ANTHROPIC_API_KEY.

Tips and common issues:

• Ensure you have network access to MLB Stats API endpoints; some hosts may block external requests.
• If you encounter authentication or API quota issues with Anthropics (ANTHROPIC_API_KEY), verify the key is valid and has the necessary permissions.
• Configure logging levels via MLB_STATS_LOG_LEVEL to DEBUG during development for more verbose output.
• MLB_STATS_LOG_FILE is optional; if omitted, logs go to stdout.
• When integrating with Claude Desktop, use the provided template in your claude_desktop_config.json and adjust {PATH_TO_UV}, {PROJECT_DIRECTORY}, and {LOG_FILE_PATH} accordingly.
• Running tests: uv run pytest -v to validate tool functionality and MCP protocol adherence.