Mlb Api MCP

🚀 MLB API MCP Server

This Model Context Protocol (MCP) server offers comprehensive access to MLB statistics and baseball data through a FastMCP-based interface, bridging the gap between AI applications and MLB data sources.

🚀 Quick Start

Installation

There are multiple ways to install the MLB API MCP Server.

Installing via Smithery

Automatically install the MLB API Server for Claude Desktop via Smithery:

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

Local Installation

1. Install uv if not already installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone the repository:

git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp

3. Create and activate a virtual environment:

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

4. Install dependencies:

uv pip install -e .

Docker Installation

1. Clone the repository:

git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp

2. Build the Docker image:

docker build -t mlb-api-mcp .

3. Run the container (default timezone is UTC, uses Python 3.12):

docker run -p 8000:8000 mlb-api-mcp

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.

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

✨ Features

MLB Data Access

• Current standings: Get current standings for all MLB teams with flexible filtering by league, season, and date.
• Game schedules and results: Support date range queries for game schedules and results.
• Player statistics: Include traditional and sabermetric stats (WAR, wOBA, wRC+).
• Team information and rosters: Provide various roster types.
• Live game data: Such as boxscores, linescores, and play-by-play.
• Game highlights and scoring plays: Offer video highlights and scoring plays.
• Player and team search: Provide search functionality for players and teams.
• Draft information and award recipients: Offer draft information and details of award recipients.
• Game pace statistics and lineup information: Provide game pace statistics and lineup details.

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: Get current MLB standings with league and season filters.
• get_mlb_schedule: Get game schedules for specific dates, ranges, or teams.
• get_mlb_team_info: Get detailed team information.
• get_mlb_player_info: Get player biographical information.
• get_mlb_boxscore: Get complete game boxscores.
• get_mlb_linescore: Get inning-by-inning game scores.
• get_mlb_game_highlights: Get video highlights for games.
• get_mlb_game_scoring_plays: Get play-by-play data with event filtering.
• get_mlb_game_pace: Get game duration and pace statistics.
• get_mlb_game_lineup: Get detailed lineup information for games.
• get_multiple_mlb_player_stats: Get traditional player statistics.
• get_mlb_sabermetrics: Get advanced sabermetric statistics (WAR, wOBA, etc.).
• get_mlb_roster: Get 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: Get all players for a sport/season.
• get_mlb_teams: Get all teams for a sport/season.
• get_mlb_draft: Get draft information by year.
• get_mlb_awards: Get award recipients.
• get_current_date: Get the current date.
• get_current_time: Get the current time.

HTTP Endpoints

• /: 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

⚠️ Important 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

The installation methods have been detailed in the Quick Start section.

💻 Usage Examples

Basic Usage

Integrate the server into an MCP-compatible application to retrieve team standings:

# Assume there is a proper MCP client setup
mcp_client = setup_mcp_client()
standings_tool = mcp_client.get_tool('get_mlb_standings')
standings = standings_tool(league='AL', season=2024)
print(standings)

Advanced Usage

Get comprehensive player statistics and sabermetric data:

mcp_client = setup_mcp_client()
player_stats_tool = mcp_client.get_tool('get_multiple_mlb_player_stats')
sabermetrics_tool = mcp_client.get_tool('get_mlb_sabermetrics')
player_id = 12345
player_stats = player_stats_tool(player_id=player_id)
sabermetrics = sabermetrics_tool(player_id=player_id)
print(f"Player stats: {player_stats}, Sabermetrics: {sabermetrics}")

📚 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

🔧 Technical Details

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

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

📄 License

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

Testing

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%

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