Skip to main content
Glama

mlb-api-mcp

by guillochon
GitHub
Python
MIT License
16
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MLB API MCP Server

License Coverage

A Model Context Protocol (MCP) server that provides comprehensive access to MLB statistics and baseball data through a FastMCP-based interface.

Overview

This MCP server acts as a bridge between AI applications and MLB data sources, enabling seamless integration of baseball statistics, game information, player data, and more into AI workflows and applications.

Features

MLB Data Access

  • Current standings for all MLB teams with flexible filtering by league, season, and date
  • Game schedules and results with date range support
  • Player statistics including traditional and sabermetric stats (WAR, wOBA, wRC+)
  • Team information and rosters with various roster types
  • Live game data including boxscores, linescores, and play-by-play
  • Game highlights and scoring plays
  • Player and team search functionality
  • Draft information and award recipients
  • Game pace statistics and lineup information

MCP Tools

All MLB/statistics/game/player/team/etc. functionality is exposed as MCP tools, not as RESTful HTTP endpoints. These tools are accessible via the /mcp/ endpoint using the MCP protocol. For a list of available tools and their descriptions, visit /tools/ when the server is running.

Key MCP Tools
  • get_mlb_standings - Current MLB standings with league and season filters
  • get_mlb_schedule - Game schedules for specific dates, ranges, or teams
  • get_mlb_team_info - Detailed team information
  • get_mlb_player_info - Player biographical information
  • get_mlb_boxscore - Complete game boxscores
  • get_mlb_linescore - Inning-by-inning game scores
  • get_mlb_game_highlights - Video highlights for games
  • get_mlb_game_scoring_plays - Play-by-play data with event filtering
  • get_mlb_game_pace - Game duration and pace statistics
  • get_mlb_game_lineup - Detailed lineup information for games
  • get_multiple_mlb_player_stats - Traditional player statistics
  • get_mlb_sabermetrics - Advanced sabermetric statistics (WAR, wOBA, etc.)
  • get_mlb_roster - Team rosters with various roster types
  • get_mlb_search_players - Search players by name
  • get_mlb_search_teams - Search teams by name
  • get_mlb_players - All players for a sport/season
  • get_mlb_teams - All teams for a sport/season
  • get_mlb_draft - Draft information by year
  • get_mlb_awards - Award recipients
  • get_current_date - Current date
  • get_current_time - Current time

For the full list and detailed descriptions, see /tools/ or /docs when the server is running.

HTTP Endpoints

The following HTTP endpoints are available:

  • / - Redirects to /docs
  • /docs - Interactive API documentation and tool listing
  • /health/ - Health check endpoint
  • /mcp/info - MCP server information
  • /tools/ - List of all available MCP tools
  • /mcp/ (POST) - MCP protocol endpoint for MCP-compatible clients

Note: There are no RESTful HTTP endpoints for MLB/statistics/game/player/team/etc. All such functionality is accessed via MCP tools through the /mcp/ endpoint.

MCP Integration

  • Compatible with MCP-enabled AI applications
  • Tool-based interaction model with comprehensive endpoint descriptions
  • Automatic API documentation generation
  • Schema validation and type safety
  • Full response schema descriptions for better AI integration

Installation

Installing via Smithery

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

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

Option 1: Local Installation

  1. Install uv if you haven't already:
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Clone the repository:
git clone https://github.com/guillochon/mlb-api-mcp.git cd mlb-api-mcp
  1. Create and activate a virtual environment:
uv venv source .venv/bin/activate # On Unix/macOS # or .venv\Scripts\activate # On Windows
  1. Install dependencies:
uv pip install -e .

Option 2: Docker Installation

  1. Clone the repository:
git clone https://github.com/guillochon/mlb-api-mcp.git cd mlb-api-mcp
  1. Build the Docker image:
docker build -t mlb-api-mcp .
  1. Run the container (default timezone is UTC, uses Python 3.12):
docker run -p 8000:8000 mlb-api-mcp
Setting the Timezone

To run the container in your local timezone, pass the TZ environment variable (e.g., for New York):

docker run -e TZ=America/New_York -p 8000:8000 mlb-api-mcp

Replace America/New_York with your desired IANA timezone name.

The server will be available at http://localhost:8000 with:

  • MCP Server: http://localhost:8000/mcp/
  • Documentation: http://localhost:8000/docs
Docker Options

You can also run the container with additional options:

# Run in detached mode docker run -d -p 8000:8000 --name mlb-api-server mlb-api-mcp # Run with custom port mapping docker run -p 3000:8000 mlb-api-mcp # View logs docker logs mlb-api-server # Stop the container docker stop mlb-api-server # Remove the container docker rm mlb-api-server

Usage

Starting the Server

Run the MCP server locally:

# For stdio transport (default, for MCP clients like Smithery) uv run python main.py # For HTTP transport (for web access) uv run python main.py --http

The server will start with:

  • MCP Server on http://localhost:8000/mcp/
  • Interactive API documentation available at http://localhost:8000/docs

MCP Client Integration

This server can be integrated into any MCP-compatible application. The server provides tools for:

  • Retrieving team standings and schedules
  • Getting comprehensive player and team statistics
  • Accessing live game data and historical records
  • Searching for players and teams
  • Fetching sabermetric statistics like WAR
  • And much more...

API Documentation

Once the server is running, visit http://localhost:8000/docs for comprehensive API documentation including:

  • Available HTTP endpoints
  • List of all available MCP tools at /tools/
  • Tool descriptions and parameters
  • Interactive testing interface
  • Parameter descriptions and examples

Dependencies

  • mcp[cli]: MCP-compliant server framework with CLI support
  • FastAPI: Web framework for HTTP transport
  • python-mlb-statsapi: Official MLB Statistics API wrapper
  • uvicorn[standard]: ASGI server for running the app
  • websockets: WebSocket support (latest version to avoid deprecation warnings)
  • python-dotenv: Environment variable management
  • httpx: HTTP client for API requests

Development

This project uses:

  • Python 3.10+ (Docker uses Python 3.12)
  • FastMCP for the web framework
  • uv for fast Python package management
  • Hatchling for build management
  • MLB Stats API for comprehensive baseball data access
  • Ruff for linting and formatting

Setup Pre-commit Hooks

  1. Install pre-commit:
pip install pre-commit
  1. 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

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This project is open source. Please check the license file for details.

Testing

This project includes comprehensive test coverage with pytest and coverage reporting.

Running Tests

# Run all tests with coverage (default) uv run pytest # Run tests with verbose output uv run pytest -v # Run specific test file uv run pytest tests/test_mlb_api.py # Run specific test function uv run pytest tests/test_mlb_api.py::test_get_mlb_standings # Run tests without coverage uv run tests/run_coverage.py test # Generate HTML coverage report uv run tests/run_coverage.py html # Clean up coverage files uv run tests/run_coverage.py clean

Coverage

  • Current Coverage: 86.27% (exceeds 80% threshold)
  • Coverage Source: mlb_api.py and generic_api.py
  • Reports: Terminal output, HTML (htmlcov/index.html), and XML (coverage.xml)
  • CI Integration: Coverage checking and badge updates run automatically on every push/PR

Test Structure

The test suite includes:

  • Unit tests for all MCP tools (MLB API and Generic API)
  • Error handling tests for API failures
  • Edge case tests for boundary conditions
  • Mock-based tests to avoid external API calls

Adding New Tests

When adding new functionality:

  1. Add corresponding test cases to tests/test_mlb_api.py
  2. Include both success and error scenarios
  3. Use mocking to avoid external dependencies
  4. Ensure coverage remains above 80%

Example test structure:

def test_new_function_success(mcp): """Test successful execution of new function""" new_function = get_tool(mcp, 'new_function') with patch('mlb_api.external_api_call', return_value={'data': 'success'}): result = new_function(param='value') assert 'data' in result def test_new_function_error_handling(mcp): """Test error handling in new function""" new_function = get_tool(mcp, 'new_function') with patch('mlb_api.external_api_call', side_effect=Exception("API Error")): result = new_function(param='value') assert 'error' in result

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Python MCP server that provides comprehensive access to MLB statistics and baseball data through a FastAPI-based interface. Acts as a bridge between AI applications and MLB data sources, enabling seamless integration of baseball statistics, game information, player data, and more.

  1. Overview
    1. Features
      1. MLB Data Access
      2. MCP Tools
      3. HTTP Endpoints
      4. MCP Integration
    2. Installation
      1. Installing via Smithery
      2. Option 1: Local Installation
      3. Option 2: Docker Installation
    3. Usage
      1. Starting the Server
      2. MCP Client Integration
    4. API Documentation
      1. Dependencies
        1. Development
          1. Setup Pre-commit Hooks
        2. Contributing
          1. License
            1. Testing
              1. Running Tests
              2. Coverage
              3. Test Structure
              4. Adding New Tests

            Related MCP Servers

            • balldontlie-mcp

              mikechao
              A
              security
              A
              license
              A
              quality
              An MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.
              Last updated -
              4
              3,877
              11
              JavaScript
              MIT License

            • Model Context Protocol (MCP) Server

              suspicious-cow
              -
              security
              F
              license
              -
              quality
              A Python implementation of the MCP server that enables AI models to connect with external tools and data sources through a standardized protocol, supporting tool invocation and resource access via JSON-RPC.
              Last updated -
              1
              Python

            • MLB Projections MCP Server

              ag2-mcp-servers
              -
              security
              F
              license
              -
              quality
              An MCP server that enables interaction with MLB (Major League Baseball) v3 projections through the SportsData.io API, allowing access to baseball statistics and projections through natural language.
              Last updated -
              Python

            • MLB V3 Scores MCP Server

              ag2-mcp-servers
              -
              security
              F
              license
              -
              quality
              An MCP Server that enables interaction with MLB scores and statistics via the SportsData.io MLB V3 Scores API, allowing users to access baseball data through natural language queries.
              Last updated -
              Python

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/guillochon/mlb-api-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server