A Model Context Protocol (MCP) server that provides comprehensive access to MLB statistics and baseball data through a FastMCP-based interface. 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. - Current standings for all MLB teams with flex
Add this skill
npx mdskills install guillochon/mlb-api-mcpComprehensive MLB data access with 20+ well-documented tools and excellent setup instructions
1# MLB API MCP Server23[](https://github.com/guillochon/mlb-api-mcp/actions/workflows/ci.yml)45[](https://smithery.ai/server/@guillochon/mlb-api-mcp)678A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides comprehensive access to MLB statistics and baseball data through a FastMCP-based interface.910## Overview1112This 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.1314## Features1516### MLB Data Access17- **Current standings** for all MLB teams with flexible filtering by league, season, and date18- **Game schedules** and results with date range support19- **Player statistics** including traditional and sabermetric stats (WAR, wOBA, wRC+)20- **Team information** and rosters with various roster types21- **Live game data** including boxscores, linescores, and play-by-play22- **Game highlights** and scoring plays23- **Player and team search** functionality24- **Draft information** and award recipients25- **Game pace statistics** and lineup information2627### MCP Tools2829All 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.3031#### Key MCP Tools32- `get_mlb_standings` - Current MLB standings with league and season filters33- `get_mlb_schedule` - Game schedules for specific dates, ranges, or teams34- `get_mlb_team_info` - Detailed team information35- `get_mlb_player_info` - Player biographical information36- `get_mlb_boxscore` - Complete game boxscores37- `get_mlb_linescore` - Inning-by-inning game scores38- `get_mlb_game_highlights` - Video highlights for games39- `get_mlb_game_scoring_plays` - Play-by-play data with event filtering40- `get_mlb_game_pace` - Game duration and pace statistics41- `get_mlb_game_lineup` - Detailed lineup information for games42- `get_multiple_mlb_player_stats` - Traditional player statistics43- `get_mlb_sabermetrics` - Advanced sabermetric statistics (WAR, wOBA, etc.)44- `get_mlb_roster` - Team rosters with various roster types45- `get_mlb_search_players` - Search players by name46- `get_mlb_search_teams` - Search teams by name47- `get_mlb_players` - All players for a sport/season48- `get_mlb_teams` - All teams for a sport/season49- `get_mlb_draft` - Draft information by year50- `get_mlb_awards` - Award recipients51- `get_current_date` - Current date52- `get_current_time` - Current time5354For the full list and detailed descriptions, see `/tools/` or `/docs` when the server is running.5556### HTTP Endpoints5758The following HTTP endpoints are available:59- `/` - Redirects to `/docs`60- `/docs` - Interactive API documentation and tool listing61- `/health/` - Health check endpoint62- `/mcp/info` - MCP server information63- `/tools/` - List of all available MCP tools64- `/mcp/` (POST) - MCP protocol endpoint for MCP-compatible clients6566> **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.6768### MCP Integration69- Compatible with MCP-enabled AI applications70- Tool-based interaction model with comprehensive endpoint descriptions71- Automatic API documentation generation72- Schema validation and type safety73- Full response schema descriptions for better AI integration7475## Installation7677### Installing via Smithery7879To install MLB API Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@guillochon/mlb-api-mcp):8081```bash82npx -y @smithery/cli install @guillochon/mlb-api-mcp --client claude83```8485### Option 1: Local Installation86871. Install uv if you haven't already:8889```bash90curl -LsSf https://astral.sh/uv/install.sh | sh91```92932. Clone the repository:94```bash95git clone https://github.com/guillochon/mlb-api-mcp.git96cd mlb-api-mcp97```98993. Create and activate a virtual environment:100101```bash102uv venv103source .venv/bin/activate # On Unix/macOS104# or105.venv\Scripts\activate # On Windows106```1071084. Install dependencies:109110```bash111uv pip install -e .112```113114### Option 2: Docker Installation1151161. Clone the repository:117```bash118git clone https://github.com/guillochon/mlb-api-mcp.git119cd mlb-api-mcp120```1211222. Build the Docker image:123```bash124docker build -t mlb-api-mcp .125```1261273. Run the container (default timezone is UTC, uses Python 3.12):128```bash129docker run -p 8000:8000 mlb-api-mcp130```131132#### Setting the Timezone133134To run the container in your local timezone, pass the `TZ` environment variable (e.g., for New York):135136```bash137docker run -e TZ=America/New_York -p 8000:8000 mlb-api-mcp138```139140Replace `America/New_York` with your desired [IANA timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).141142The server will be available at `http://localhost:8000` with:143- **MCP Server**: `http://localhost:8000/mcp/`144- **Documentation**: `http://localhost:8000/docs`145146#### Docker Options147148You can also run the container with additional options:149150```bash151# Run in detached mode152docker run -d -p 8000:8000 --name mlb-api-server mlb-api-mcp153154# Run with custom port mapping155docker run -p 3000:8000 mlb-api-mcp156157# View logs158docker logs mlb-api-server159160# Stop the container161docker stop mlb-api-server162163# Remove the container164docker rm mlb-api-server165```166167## Usage168169### Starting the Server170171Run the MCP server locally:172```bash173# For stdio transport (default, for MCP clients like Smithery)174uv run python main.py175176# For HTTP transport (for web access)177uv run python main.py --http178```179180The server will start with:181- **MCP Server** on `http://localhost:8000/mcp/`182- **Interactive API documentation** available at `http://localhost:8000/docs`183184### MCP Client Integration185186This server can be integrated into any MCP-compatible application. The server provides tools for:187- Retrieving team standings and schedules188- Getting comprehensive player and team statistics189- Accessing live game data and historical records190- Searching for players and teams191- Fetching sabermetric statistics like WAR192- And much more...193194## API Documentation195196Once the server is running, visit `http://localhost:8000/docs` for comprehensive API documentation including:197- Available HTTP endpoints198- List of all available MCP tools at `/tools/`199- Tool descriptions and parameters200- Interactive testing interface201- Parameter descriptions and examples202203## Dependencies204205- **mcp[cli]**: MCP-compliant server framework with CLI support206- **FastAPI**: Web framework for HTTP transport207- **python-mlb-statsapi**: Official MLB Statistics API wrapper208- **uvicorn[standard]**: ASGI server for running the app209- **websockets**: WebSocket support (latest version to avoid deprecation warnings)210- **python-dotenv**: Environment variable management211- **httpx**: HTTP client for API requests212213## Development214215This project uses:216- Python 3.10+ (Docker uses Python 3.12)217- FastMCP for the web framework218- uv for fast Python package management219- Hatchling for build management220- MLB Stats API for comprehensive baseball data access221- Ruff for linting and formatting222223### Setup Pre-commit Hooks2242251. Install pre-commit:226227```bash228pip install pre-commit229```2302312. Initialize pre-commit hooks:232233```bash234pre-commit install235```236237Now, the linting checks will run automatically whenever you commit code. You can also run them manually:238239```bash240pre-commit run --all-files241```242243## Contributing244245Contributions are welcome! Please feel free to submit issues or pull requests.246247## License248249This project is open source. Please check the license file for details.250251## Testing252253This project includes comprehensive test coverage with pytest and coverage reporting.254255### Running Tests256257```bash258# Run all tests with coverage (default)259uv run pytest260261# Run tests with verbose output262uv run pytest -v263264# Run specific test file265uv run pytest tests/test_mlb_api.py266267# Run specific test function268uv run pytest tests/test_mlb_api.py::test_get_mlb_standings269270# Run tests without coverage271uv run tests/run_coverage.py test272273# Generate HTML coverage report274uv run tests/run_coverage.py html275276# Clean up coverage files277uv run tests/run_coverage.py clean278```279280### Coverage281282- **Current Coverage**: 86.27% (exceeds 80% threshold)283- **Coverage Source**: `mlb_api.py` and `generic_api.py`284- **Reports**: Terminal output, HTML (`htmlcov/index.html`), and XML (`coverage.xml`)285- **CI Integration**: Coverage checking and badge updates run automatically on every push/PR286287### Test Structure288289The test suite includes:290- **Unit tests** for all MCP tools (MLB API and Generic API)291- **Error handling tests** for API failures292- **Edge case tests** for boundary conditions293- **Mock-based tests** to avoid external API calls294295### Adding New Tests296297When adding new functionality:2982991. Add corresponding test cases to `tests/test_mlb_api.py`3002. Include both success and error scenarios3013. Use mocking to avoid external dependencies3024. Ensure coverage remains above 80%303304Example test structure:305```python306def test_new_function_success(mcp):307 """Test successful execution of new function"""308 new_function = get_tool(mcp, 'new_function')309 with patch('mlb_api.external_api_call', return_value={'data': 'success'}):310 result = new_function(param='value')311 assert 'data' in result312313def test_new_function_error_handling(mcp):314 """Test error handling in new function"""315 new_function = get_tool(mcp, 'new_function')316 with patch('mlb_api.external_api_call', side_effect=Exception("API Error")):317 result = new_function(param='value')318 assert 'error' in result319```320
Full transparency — inspect the skill content before installing.