nba_mcp_server

This MCP server serves up comprehensive NBA data via the Model Context Protocol. It exposes tools to fetch player and team information, live game data, standings, league leaders, shooting analytics, and more. Clients can request detailed player bios, season and career stats, game logs, box scores, play-by-play data, and visual assets such as player headshots and team logos. The server returns structured JSON responses following the MCP format, with embedded public CDN URLs for visuals when available. You can query capabilities like get_player_info, get_team_roster, get_todays_scoreboard, get_game_details, get_box_score, and get_shot_chart, among many others. Use the provided tools through clients compatible with MCP (e.g., Claude, Strands) to compose rich queries that combine multiple endpoints within a single JSON response. The server is designed to handle live NBA data as well as historical stats, with configurable caching and retry settings to balance freshness and reliability.

Prerequisites:

• Python 3.10+ (recommended)
• git (optional for cloning from source)
• pip (for installation)

Install from PyPI (recommended):

pip install nba-stats-mcp

Install from source:

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

Run the MCP server (example using uvx, as described in the docs):

uvx nba-stats-mcp

If you prefer running via uv directly (from source):

uv run nba-stats-mcp

Or run directly (if installed as a package):

python -m nba_mcp_server

Note: The server exposes a CLI name nba-stats-mcp for starting the MCP service. The installation options section of the README also documents usage with uv and pip, and the inspector/testing workflow with MCP Inspector.

Tips and common considerations:

• Environment variables: Use NBA_MCP_LOG_LEVEL to control verbosity during debugging. Other tuning vars (timeouts, retries, and cache TTLs) can significantly impact performance and reliability; adjust as needed for your environment.
• If running behind a proxy or in restricted networks, ensure outbound access to NBA data endpoints is allowed and TLS certificates are verifiable (set NBA_MCP_TLS_VERIFY accordingly).
• When testing with Claude Desktop, you can either point to a prebuilt binary via uvx/nba-stats-mcp, or run from source with uv run nba-stats-mcp.
• The server returns visual asset URLs (headshots and logos) that are publicly hosted; ensure your downstream UI clients render these assets securely and handle possible CDN outages gracefully.
• If you see timeouts or rate-limiting from NBA APIs, consider increasing retries or adjusting the MAX_CONCURRENCY to avoid overwhelming upstream services.
• For debugging, enable verbose logging, then gradually revert to default settings once stability is confirmed.