NBA MCP Server (Python)

A Model Context Protocol (MCP) server that provides access to live and historical NBA data. Query game scores, player statistics, team standings, and historical performance data.

Features

• Live Game Data: Get real-time scores and game status for today's games
• Historical Games: Query games by specific date
• Player Statistics: Current season stats including points, rebounds, assists, and more
• Team Standings: Current NBA team standings with wins, losses, and rankings
• Historical Data: Access player and team statistics from previous seasons
• Team Analytics: Advanced team metrics and performance data

Installation

Using pip

cd nba-mcp-python
pip install -e .

Using uv (recommended)

cd nba-mcp-python
uv pip install -e .

Usage

As an MCP Server

Add this server to your MCP client configuration. For Claude Desktop, add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Using Python directly

{
  "mcpServers": {
    "nba": {
      "command": "python",
      "args": ["-m", "nba_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/nba-mcp-python/src"
      }
    }
  }
}

Using uv (recommended)

{
  "mcpServers": {
    "nba": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/nba-mcp-python", "run", "nba-mcp-server"]
    }
  }
}

Available Tools

1. get_todays_games

Get today's NBA games with live scores and game status.

Parameters: None

Example:

Get today's NBA games

2. get_games_by_date

Get NBA games for a specific date.

Parameters:

• date (string, required): Date in YYYY-MM-DD format

Example:

Get NBA games from 2024-10-13

3. get_player_stats

Get current season player statistics.

Parameters:

• playerName (string, optional): Filter by player name
• limit (number, optional): Max number of players to return (default: 50)

Examples:

Get stats for LeBron James
Get top 20 player stats

4. get_team_standings

Get current NBA team standings.

Parameters: None

Example:

Show me the current NBA standings

5. get_historical_player_stats

Get historical player statistics for a specific season.

Parameters:

• playerId (string, required): NBA player ID
• season (string, required): Season in YYYY-YY format

Example:

Get LeBron James stats from 2020-21 season

6. get_team_stats

Get team statistics for a specific season.

Parameters:

• season (string, optional): Season in YYYY-YY format (default: current season)

Example:

Get team stats for 2023-24 season

Development

Running the server directly

cd nba-mcp-python
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
python -m nba_mcp_server.server

Testing the API

import asyncio
from nba_mcp_server.nba_api import get_todays_games, get_games_by_date

async def test():
    # Get today's games
    games = await get_todays_games()
    print(f"Found {len(games)} games today")

    # Get games for a specific date
    games = await get_games_by_date("2024-10-22")
    for game in games:
        print(f"{game.away_team} @ {game.home_team}: {game.game_status}")

asyncio.run(test())

Data Source

This server uses ESPN's public API to fetch data. The API provides comprehensive statistics and game information for all NBA games and players.

Project Structure

nba-mcp-python/
├── src/
│   └── nba_mcp_server/
│       ├── __init__.py       # Package initialization
│       ├── nba_api.py        # NBA API client
│       └── server.py         # MCP server implementation
├── pyproject.toml            # Project metadata and dependencies
├── requirements.txt          # Python dependencies
└── README.md                 # This file

License

MIT