nba-stats-mcp 0.3.0

MCP server for accessing NBA statistics and data via direct API calls

NBA MCP Server

Access NBA statistics via the Model Context Protocol (MCP).

This package runs an MCP server with 21 consolidated tools — live scores, box scores, standings, player/team stats, play-by-play, shot charts, and more. All tools accept human names (not just IDs), return structured data + compact text, and default season to current.

Supports stdio, streamable HTTP, and SSE transports. No API key required.

Quick Start

With uvx (Recommended - No Install Required)

Add to your MCP client config (e.g., Claude Desktop):

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"]
    }
  }
}

Restart your client and start asking!

With pip

pip install nba-stats-mcp

Then configure your MCP client:

{
  "mcpServers": {
    "nba-stats": {
      "command": "nba-stats-mcp"
    }
  }
}

Response Format (v3.0)

All tools return JSON (encoded in the MCP TextContent.text field). Each response includes:

• text — compact 1-3 line summary (clean, no IDs or URLs)
• data — structured dict with all values (primary output for programmatic use)
• entities — extracted IDs + asset URLs for UI rendering

Example:

{
  "tool_name": "get_player_stats",
  "arguments": {"player": "LeBron James", "stat_type": "season"},
  "text": "LeBron James 2025-26: 25.3 PPG, 7.1 RPG, 7.8 APG (51.2% FG)",
  "data": {
    "player_id": 2544, "name": "LeBron James", "season": "2025-26",
    "pts": 25.3, "reb": 7.1, "ast": 7.8, "fg_pct": 0.512
  },
  "entities": {
    "players": [{"player_id": "2544", "headshot_url": "https://cdn.nba.com/headshots/nba/latest/1040x760/2544.png"}]
  }
}

What You Can Ask

• "Show me today's NBA games"
• "What are LeBron James' stats this season?"
• "Compare LeBron and Curry"
• "Give me a team overview for the Lakers"
• "Who are the top 10 scorers this season?"
• "Show me all-time assists leaders"
• "When do the Celtics play next?"

Features

21 consolidated tools (optimized for LLM clients):

• All tools accept names — get_player_stats(player="LeBron James") works
• Structured data field for programmatic access
• 3 new composite tools: compare_players, daily_summary, team_overview
• Live game scores and play-by-play
• Player stats (season, career, game log, hustle, defense, advanced)
• Team rosters and advanced metrics
• League standings and leaders (current season, all-time, hustle)
• Shot charts and shooting analytics

Full Documentation & Tool Reference

Requirements

• Python 3.10+
• An MCP-compatible client

License

MIT License - See LICENSE for details.