labeveryday/nba_mcp_server

PyPI version Python 3.10+ License: MIT Tests Code style: ruff

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

1. Install the server:

# 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

2. Add to your Claude Desktop config file:

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

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

Or if you installed from source:

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

3. 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)

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

With pip

pip install nba-stats-mcp

From source

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

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)

# 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)

# 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

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):

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

In Claude Desktop config:

{
  "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:

{
  "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

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

Code Quality

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

Security (Bandit)

Static security analysis:

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

Releasing to PyPI

This project uses Hatchling for builds. Recommended release steps:

# 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