Skip to main content
Glama
nba-stats-mcp

nba-stats-mcp

by 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
  1. 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"
      ]
    }
  }
}
  1. Restart Claude Desktop

Related MCP server: NBA MCP Server

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

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:

Available Tools

21 tools
compare_playersC

Compare two players side by side. Accepts names or IDs.

Inputs: player1 (required), player2 (required), season. Returns: result

daily_summaryB

All games + scores for a date. Defaults to today.

Inputs: date. Returns: result

find_gameB

Find game_id by team matchup and optional date. Accepts team names.

Inputs: team1 (required), team2, date. Returns: result

get_box_scoreB

Full box score with player stats. Accepts game_id.

Inputs: game_id (required). Returns: result

get_game_detailsC

Detailed game info. Accepts game_id.

Inputs: game_id (required). Returns: result

get_game_rotationC

Player rotation/substitution data for a game.

Inputs: game_id (required). Returns: result

get_leadersC

League leaders. scope: current_season (default), all_time, hustle. category: points, assists, rebounds, etc.

Inputs: category, scope, season, limit. Returns: result

get_play_by_playC

Play-by-play data for a game.

Inputs: game_id (required), start_period, end_period. Returns: result

get_player_awardsB

Player awards/accolades. Accepts player name or ID.

Inputs: player (required). Returns: result

get_player_infoB

Player bio/profile. Accepts player name or ID.

Inputs: player (required). Returns: result

get_player_statsC

Player stats. stat_type: season (default), career, game_log, hustle, defense, advanced. Accepts player name or ID.

Inputs: player (required), stat_type, season. Returns: result

get_scheduleC

Team upcoming schedule. Accepts team name or ID.

Inputs: team (required), days_ahead. Returns: result

get_scoreboardB

Games for a date (YYYY-MM-DD or YYYYMMDD). Defaults to today.

Inputs: date. Returns: result

get_season_awardsC

Major award winners for a season (MVP, etc.).

Inputs: season. Returns: result

get_shooting_dataC

Shooting data. data_type: splits (default) or chart. Accepts player name or ID.

Inputs: player (required), data_type, season, game_id. Returns: result

get_standingsC

League standings by conference.

Inputs: season. Returns: result

get_team_advanced_statsB

Team advanced metrics (ORtg, DRtg, pace, net rating). Accepts team name or ID.

Inputs: team (required), season. Returns: result

get_team_rosterB

Team roster. Accepts team name or ID.

Inputs: team (required), season. Returns: result

resolve_player_idA

Resolve player name to player_id. Returns top matches with active/inactive status.

Inputs: query (required), active_only, limit. Returns: result

resolve_team_idA

Resolve team name/city/nickname to team_id. Returns top matches.

Inputs: query (required), limit. Returns: result

team_overviewA

Team overview: roster + record + upcoming schedule. Accepts team name or ID.

Inputs: team (required), season. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have clear distinct purposes, but daily_summary and get_scoreboard both provide games for a date, creating slight overlap. Additionally, get_leaders and get_season_awards both relate to awards/leaders though they differ in scope.

    Naming Consistency3/5

    Naming conventions are mixed: many tools use a 'get_' prefix, but some like compare_players, daily_summary, and find_game omit it, and resolve_player_id/team_id use a 'resolve_' prefix. This inconsistency could confuse an agent.

    Tool Count4/5

    With 21 tools covering players, teams, games, and leagues, the count is on the higher side but remains reasonable for a comprehensive NBA stats server. It's well-scoped without being excessive.

    Completeness4/5

    The tool set covers a wide range of NBA data including player info/stats, team rosters/schedules, game details, and league leaders. Minor gaps exist, such as missing team basic stats or historical data, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides comprehensive NBA player statistics from basketball-reference.com, delivering detailed stats including career summaries, season comparisons, advanced metrics, and shooting analytics.
      5
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to retrieve NBA data including player stats, team information, game logs, and league standings through the nba_api library.
      10
      1
      -
    • F
      license
      B
      quality
      D
      maintenance
      Provides natural language access to IPL cricket match data, allowing users to query player statistics, team performances, and match results. It utilizes a SQLite backend and Cricsheet data to deliver detailed cricket analytics through the Model Context Protocol.
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible LLM clients to access live NBA data, including stats, standings, rosters, scores, and box scores via callable tools.
      9
      MIT