Uses FastAPI as the web framework for building the API, providing automatic API documentation generation, schema validation, and type safety for the MLB data endpoints.
Repository is hosted on GitHub, allowing for version control, collaboration, and distribution of the MCP server code.
Provides comprehensive access to MLB statistics and baseball data, including team standings, game schedules, player statistics, team information, live game data, game highlights, player and team search, draft information, and advanced sabermetrics.
Built with Python 3.10+, utilizing Python's capabilities for data processing and API integration with the MLB Stats API.
MLB API MCP Server
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 filtersget_mlb_schedule
- Game schedules for specific dates, ranges, or teamsget_mlb_team_info
- Detailed team informationget_mlb_player_info
- Player biographical informationget_mlb_boxscore
- Complete game boxscoresget_mlb_linescore
- Inning-by-inning game scoresget_mlb_game_highlights
- Video highlights for gamesget_mlb_game_scoring_plays
- Play-by-play data with event filteringget_mlb_game_pace
- Game duration and pace statisticsget_mlb_game_lineup
- Detailed lineup information for gamesget_multiple_mlb_player_stats
- Traditional player statisticsget_mlb_sabermetrics
- Advanced sabermetric statistics (WAR, wOBA, etc.)get_mlb_roster
- Team rosters with various roster typesget_mlb_search_players
- Search players by nameget_mlb_search_teams
- Search teams by nameget_mlb_players
- All players for a sport/seasonget_mlb_teams
- All teams for a sport/seasonget_mlb_draft
- Draft information by yearget_mlb_awards
- Award recipientsget_current_date
- Current dateget_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:
Option 1: Local Installation
Install uv if you haven't already:
Clone the repository:
Create and activate a virtual environment:
Install dependencies:
Option 2: Docker Installation
Clone the repository:
Build the Docker image:
Run the container (default timezone is UTC, uses Python 3.12):
Setting the Timezone
To run the container in your local timezone, pass the TZ
environment variable (e.g., for New York):
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:
Usage
Starting the Server
Run the MCP server locally:
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
Install pre-commit:
Initialize pre-commit hooks:
Now, the linting checks will run automatically whenever you commit code. You can also run them manually:
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
Coverage
Current Coverage: 86.27% (exceeds 80% threshold)
Coverage Source:
mlb_api.py
andgeneric_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:
Add corresponding test cases to
tests/test_mlb_api.py
Include both success and error scenarios
Use mocking to avoid external dependencies
Ensure coverage remains above 80%
Example test structure:
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
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.
Related MCP Servers
- AsecurityAlicenseAqualityAn MCP Server implementation that integrates the Balldontlie API, to provide information about players, teams and games for the NBA, NFL and MLB.Last updated -42414MIT License
- -securityFlicense-qualityA 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
- -securityFlicense-qualityAn 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 -
- -securityFlicense-qualityAn 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 -