mlb-api

This MLB API MCP Server provides a centralized MCP interface for accessing comprehensive MLB data. It exposes a set of MCP tools under the /mcp/ endpoint, such as get_mlb_standings, get_mlb_schedule, get_mlb_player_info, get_mlb_boxscore, get_mlb_linescore, get_mlb_game_highlights, get_mlb_game_scoring_plays, get_mlb_game_pace, get_mlb_game_lineup, get_multiple_mlb_player_stats, get_mlb_sabermetrics, get_mlb_roster, get_mlb_search_players, get_mlb_search_teams, get_mlb_players, get_mlb_teams, get_mlb_draft, get_mlb_awards, get_current_date, and get_current_time. Tools are accessed programmatically via the MCP protocol, not through RESTful HTTP endpoints. When the server is running, you can discover available tools and their descriptions at /tools/ or /docs. The MCP model expects to issue tool-based requests to these endpoints, enabling AI workflows to fetch standings, schedules, player stats, live game data, and more without exposing individual REST endpoints. To start using the server, connect your MCP client to http://<host>:8000/mcp/ and begin invoking tools such as get_mlb_standings or get_mlb_schedule. For browsing documentation and tool details, visit http://<host>:8000/docs once the server is up.

Prerequisites:

• Python 3.10+ (Docker is tested with Python 3.12)
• uv (via the uv tool) for managing Python packages and environments
• git
• (Optional) Docker if you prefer containerized deployment

Option A: Local Installation (uv)

1. Install uv and clone the repository:

# Install uv tool if not already installed
# (follow the official uv installation instructions)

# Clone the repository
git clone https://github.com/guillochon/mlb-api-mcp.git
cd mlb-api-mcp

2. Create and activate a virtual environment and install dependencies:

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

uv pip install -e .

3. Run the server (MCP via the uv transport):

uv run python main.py

Option B: Docker Installation

1. Clone the repository and navigate into it:

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 UTC, Python 3.12):

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

4. Optional: Run with a specific timezone:

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

After installation, the server will be available at http://localhost:8000 with the MCP endpoint at http://localhost:8000/mcp/ and documentation at http://localhost:8000/docs.

Notes and tips:

• This MCP server exposes functionality through MCP tools under /mcp/ rather than RESTful endpoints. Consult /tools/ for a list of tools and their parameters.
• For container deployments, you can pass TZ to align the server's time with your environment.
• If you encounter environment-related issues, ensure Python dependencies are installed in the active environment (uvpip install -e .).
• The server relies on the MLB Stats API wrapper and related dependencies; ensure network access to fetch live data and updates.
• When using Docker, you can inspect logs with docker logs <container_name> to diagnose startup issues or runtime errors.