🏀 NBA MCP Server

Access comprehensive NBA statistics via Model Context Protocol

A Model Context Protocol (MCP) server that provides access to live and historical NBA data including player stats, game scores, team information, and advanced analytics. v0.3.0: All 21 tools accept human names (not just IDs), return structured data + compact text, and default season to current. Optimized for both large and small LLM clients.

Quick Start with Claude Desktop

Install the server:

bash

# Using uvx (recommended - no install required)
uvx nba-stats-mcp

# Or using pip
pip install nba-stats-mcp

# Or from source
git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
uv sync

Add to your Claude Desktop config file:

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

config.json

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"]
    }
  }
}

Or if you installed from source:

config.json

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

Restart Claude Desktop

What You Can Ask

"Show me today's NBA games"
"What are LeBron James' stats this season?"
"Get the box score for Lakers vs Warriors"
"Who are the top 10 scorers this season?"
"Show me all-time assists leaders"
"When do the Celtics play next?"
"Get Stephen Curry's shot chart"
"Who are the league leaders in deflections?"
"Show me Giannis' career awards"

Available Tools (21 total)

All tools accept human names — no need to resolve IDs first. Every response includes structured data + compact text.

Player Tools

get_player_info(player) - Player bio and details (accepts name or ID)
get_player_stats(player, stat_type) - Season, career, game log, hustle, defense, or advanced stats
get_player_awards(player) - All awards and accolades
get_shooting_data(player, data_type) - Shot chart or shooting splits

Team Tools

get_team_roster(team) - Team roster (accepts team name or ID)
get_team_advanced_stats(team) - Team efficiency metrics (ORtg, DRtg, pace)
get_schedule(team) - Upcoming games
get_standings() - League standings by conference

Game Tools

get_scoreboard(date?) - Games for a date (defaults to today)
find_game(team1, team2?, date?) - Find game_id by team matchup
get_game_details(game_id) - Live game info with team stats
get_box_score(game_id) - Full box score with player stats
get_play_by_play(game_id) - Play-by-play with timestamps
get_game_rotation(game_id) - Player rotation/substitution data

League Tools

get_leaders(category, scope) - Current season, all-time, or hustle leaders
get_season_awards(season?) - Season MVP and major awards

Composite Tools (new in v0.3.0)

compare_players(player1, player2) - Side-by-side player comparison
daily_summary(date?) - All games + scores for a date
team_overview(team) - Roster + record + upcoming schedule

Resolution Tools

resolve_player_id(query) - Fuzzy match player name to ID
resolve_team_id(query) - Fuzzy match team name to ID

Visual Assets (Public NBA CDN)

This MCP server also returns public NBA CDN asset URLs (no API key) alongside IDs in several tool responses, so UI clients can render visuals.

Player headshots:
- Full size: https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png
- Thumbnail: https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png
Team logos (SVG):
- https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg

Tools that include these URLs:

players: resolve_player_id, get_player_info, get_player_stats
teams: resolve_team_id, get_standings, get_team_roster

Installation Options

With uv (recommended)

bash

git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
uv sync

With pip

Terminal

pip install nba-stats-mcp

From source

bash

git clone https://github.com/labeveryday/nba-stats-mcp.git
cd nba-stats-mcp
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

Usage with Other MCP Clients

Python/Strands

server.ts

from mcp import stdio_client, StdioServerParameters
from strands.tools.mcp import MCPClient

mcp_client = MCPClient(lambda: stdio_client(
    StdioServerParameters(
        command="uvx",
        args=["nba-stats-mcp"]
    )
))

Running Standalone (for testing)

bash

# If installed via pip/uvx (stdio, default)
nba-stats-mcp

# Or from source
uv run nba-stats-mcp
# or
python -m nba_mcp_server

Streamable HTTP Transport (new in v0.2.0)

bash

# Run as an HTTP server instead of stdio
nba-stats-mcp --transport streamable-http --host 127.0.0.1 --port 8000

# Also supports SSE transport
nba-stats-mcp --transport sse --port 8000

MCP Inspector

Terminal

npx @modelcontextprotocol/inspector
# In the Inspector UI, configure a stdio server:
# - Command: uv
# - Args: --directory /absolute/path/to/nba-stats-mcp run nba-stats-mcp
#   (or Command: python, Args: -m nba_mcp_server)

JSON Response Format (v3.0)

All tools return a single JSON object (encoded as the MCP TextContent.text string). The top-level schema is:

tool_name: tool that ran
arguments: arguments passed
text: compact 1-3 line summary (clean — no IDs or CDN URLs)
data: structured dict with all machine-readable values (primary output for programmatic use)
entities: extracted IDs + asset URLs for UI rendering

Visual Assets (Public NBA CDN)

The server includes public CDN URLs (no API key required) in entities:

Player headshots:
- headshot_url: https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png
- thumbnail_url: https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png
Team logos:
- team_logo_url: https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg

Configuration

Logging Levels

Control logging verbosity with the NBA_MCP_LOG_LEVEL environment variable (default: WARNING):

server.ts

export NBA_MCP_LOG_LEVEL=INFO  # For debugging
nba-stats-mcp

In Claude Desktop config:

config.json

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"],
      "env": {
        "NBA_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Performance & Reliability Tuning

You can tune request behavior (helpful when agents do parallel tool calls) via env vars:

NBA_MCP_HTTP_TIMEOUT_SECONDS: Per-request timeout (default: 30)
NBA_MCP_MAX_CONCURRENCY: Max concurrent outbound NBA API requests (default: 8)
NBA_MCP_RETRIES: Retries for transient failures (429 / 5xx / network) (default: 2)
NBA_MCP_CACHE_TTL_SECONDS: Cache TTL for stats endpoints (default: 120)
NBA_MCP_LIVE_CACHE_TTL_SECONDS: Cache TTL for live endpoints (default: 5)
NBA_MCP_TLS_VERIFY: TLS verification enabled (default: 1). If you see PermissionError reading CA bundles (common in sandboxed/macOS privacy contexts), set to 0.

Example Claude Desktop config:

config.json

{
  "mcpServers": {
    "nba-stats": {
      "command": "uvx",
      "args": ["nba-stats-mcp"],
      "env": {
        "NBA_MCP_LOG_LEVEL": "INFO",
        "NBA_MCP_MAX_CONCURRENCY": "8",
        "NBA_MCP_CACHE_TTL_SECONDS": "120",
        "NBA_MCP_LIVE_CACHE_TTL_SECONDS": "5",
        "NBA_MCP_RETRIES": "2",
        "NBA_MCP_HTTP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Data Sources

This server uses official NBA APIs:

Live Data API - Real-time scores and game data
Stats API - Player stats, team info, historical data
Schedule API - Full season schedule including future games

Development

Running Tests

bash

uv sync --all-extras
uv run pytest
uv run pytest --cov=nba_mcp_server --cov-report=html

Code Quality

bash

uv run ruff check src/
uv run ruff format src/

Security (Bandit)

Static security analysis:

bash

uv sync --all-extras
uv run bandit -c pyproject.toml -r src/

Releasing to PyPI

This project uses Hatchling for builds. Recommended release steps:

bash

# 1) Ensure clean env + tests
uv sync --all-extras
uv run pytest
uv run ruff check src/ tests/
uv run bandit -c pyproject.toml -r src/

# 2) Build distributions
uv run python -m build

# 3) Upload
uv run twine upload dist/*

Tip: for TestPyPI uploads, use twine upload --repository testpypi dist/*.

Requirements

Python 3.10+
mcp >= 1.23.0
httpx >= 0.27.0

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please submit a Pull Request.

About the Author

This project was created by Du'An Lightfoot, a developer passionate about AI agents, cloud infrastructure, and teaching in public.

Learn more and connect:

🌐 Website: duanlightfoot.com

📺 YouTube: @LabEveryday

🐙 GitHub: @labeveryday