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. 1. Install the server: 2. Add to your Claude Desktop config file: MacOS: ~/Library/Application Support/Claude/claudedesktopconfig.json Windows: %APPDATA%/Claude/claude
Add this skill
npx mdskills install labeveryday/nba-mcp-serverComprehensive NBA stats server with 30 tools, excellent docs, and clear setup for Claude Desktop
1# 🏀 NBA MCP Server23[](https://badge.fury.io/py/nba-stats-mcp)4[](https://www.python.org/downloads/)5[](https://opensource.org/licenses/MIT)6[](https://github.com/labeveryday/nba_mcp_server)7[](https://github.com/astral-sh/ruff)89Access comprehensive NBA statistics via Model Context Protocol1011A Model Context Protocol (MCP) server that provides access to live and historical NBA data including player stats, game scores, team information, and advanced analytics.1213## Quick Start with Claude Desktop14151. Install the server:16```bash17# Using uvx (recommended - no install required)18uvx nba-stats-mcp1920# Or using pip21pip install nba-stats-mcp2223# Or from source24git clone https://github.com/labeveryday/nba_mcp_server.git25cd nba_mcp_server26uv sync27```28292. Add to your Claude Desktop config file:3031**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`32**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`3334```json35{36 "mcpServers": {37 "nba-stats": {38 "command": "uvx",39 "args": ["nba-stats-mcp"]40 }41 }42}43```4445Or if you installed from source:46```json47{48 "mcpServers": {49 "nba-stats": {50 "command": "uv",51 "args": [52 "--directory",53 "/absolute/path/to/nba_mcp_server/",54 "run",55 "nba-stats-mcp"56 ]57 }58 }59}60```61623. Restart Claude Desktop6364## What You Can Ask6566- "Show me today's NBA games"67- "What are LeBron James' stats this season?"68- "Get the box score for Lakers vs Warriors"69- "Who are the top 10 scorers this season?"70- "Show me all-time assists leaders"71- "When do the Celtics play next?"72- "Get Stephen Curry's shot chart"73- "Who are the league leaders in deflections?"74- "Show me Giannis' career awards"7576## Available Tools (30 total)7778### Server Utilities79- `get_server_info` - Server version + runtime settings (timeouts, retries, cache, concurrency)80- `resolve_team_id` - Resolve team name/city/nickname → team_id81- `resolve_player_id` - Resolve player name → player_id (official stats endpoint)82- `find_game_id` - Find game_id by date + matchup filters8384### Player Stats85- `search_players` - Find players by name86- `get_player_info` - Player bio and details87- `get_player_season_stats` - Current/historical season stats88- `get_player_career_stats` - Career totals and averages89- `get_player_game_log` - Game-by-game performance90- `get_player_awards` - All awards and accolades91- `get_player_hustle_stats` - Deflections, charges, loose balls, box outs92- `get_player_defense_stats` - Opponent FG% when defended93- `get_player_advanced_stats` - TS%, ORtg, DRtg, USG%, PIE9495### Team Stats96- `get_all_teams` - All 30 NBA teams97- `get_team_roster` - Team roster98- `get_team_advanced_stats` - Team efficiency metrics99100### Live Games101- `get_todays_scoreboard` - Today's games with live scores102- `get_scoreboard_by_date` - Games for specific date103- `get_game_details` - Detailed game info with live stats104- `get_box_score` - Full box score with player stats105- `get_play_by_play` - Complete play-by-play data106- `get_game_rotation` - Player substitution patterns107108### League Stats109- `get_standings` - Current NBA standings110- `get_league_leaders` - Statistical leaders (PTS, AST, REB, etc.)111- `get_all_time_leaders` - All-time career leaders112- `get_league_hustle_leaders` - League leaders in hustle stats113- `get_schedule` - Team schedule (up to 90 days ahead)114- `get_season_awards` - Season MVP and major awards115116### Shooting Analytics117- `get_shot_chart` - Shot locations with X/Y coordinates118- `get_shooting_splits` - Shooting % by zone and distance119120## Visual Assets (Public NBA CDN)121122This MCP server also returns **public NBA CDN asset URLs** (no API key) alongside IDs in several tool responses, so UI clients can render visuals.123124- **Player headshots**:125 - Full size: `https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png`126 - Thumbnail: `https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png`127- **Team logos (SVG)**:128 - `https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg`129130Tools that include these URLs:131- **players**: `resolve_player_id`, `search_players`, `get_player_info`132- **teams**: `resolve_team_id`, `get_all_teams`, `get_standings`133134## Installation Options135136### With uv (recommended)137```bash138git clone https://github.com/labeveryday/nba_mcp_server.git139cd nba_mcp_server140uv sync141```142143### With pip144```bash145pip install nba-stats-mcp146```147148### From source149```bash150git clone https://github.com/labeveryday/nba_mcp_server.git151cd nba_mcp_server152python -m venv .venv153source .venv/bin/activate # On Windows: .venv\Scripts\activate154pip install -e .155```156157## Usage with Other MCP Clients158159### Python/Strands160```python161from mcp import stdio_client, StdioServerParameters162from strands.tools.mcp import MCPClient163164mcp_client = MCPClient(lambda: stdio_client(165 StdioServerParameters(166 command="uvx",167 args=["nba-stats-mcp"]168 )169))170```171172### Running Standalone (for testing)173```bash174# If installed via pip/uvx175nba-stats-mcp176177# Or from source178uv run nba-stats-mcp179# or180python -m nba_mcp_server181182# or Test with MCP Inspector183# (Inspector launches a stdio server command; it is NOT the python module name.)184npx @modelcontextprotocol/inspector185# In the Inspector UI, configure a stdio server:186# - Command: uv187# - Args: --directory /absolute/path/to/nba_mcp_server run nba-stats-mcp188# (or Command: python, Args: -m nba_mcp_server)189```190191## JSON Response Format192193All tools return a **single JSON object** (encoded as the MCP `TextContent.text` string). The top-level schema is:194195- **`tool_name`**: tool that ran196- **`arguments`**: arguments passed197- **`text`**: human-readable summary (kept for debugging and display)198- **`entities`**: machine-friendly IDs + asset URLs extracted from the result199200### Visual Assets (Public NBA CDN)201202The server includes public CDN URLs (no API key required) in `entities`:203204- **Player headshots**:205 - `headshot_url`: `https://cdn.nba.com/headshots/nba/latest/1040x760/{playerId}.png`206 - `thumbnail_url`: `https://cdn.nba.com/headshots/nba/latest/260x190/{playerId}.png`207- **Team logos**:208 - `team_logo_url`: `https://cdn.nba.com/logos/nba/{teamId}/global/L/logo.svg`209210## Configuration211212### Logging Levels213214Control logging verbosity with the `NBA_MCP_LOG_LEVEL` environment variable (default: WARNING):215216```bash217export NBA_MCP_LOG_LEVEL=INFO # For debugging218nba-stats-mcp219```220221In Claude Desktop config:222```json223{224 "mcpServers": {225 "nba-stats": {226 "command": "uvx",227 "args": ["nba-stats-mcp"],228 "env": {229 "NBA_MCP_LOG_LEVEL": "INFO"230 }231 }232 }233}234```235236### Performance & Reliability Tuning237238You can tune request behavior (helpful when agents do parallel tool calls) via env vars:239240- **`NBA_MCP_HTTP_TIMEOUT_SECONDS`**: Per-request timeout (default: `30`)241- **`NBA_MCP_MAX_CONCURRENCY`**: Max concurrent outbound NBA API requests (default: `8`)242- **`NBA_MCP_RETRIES`**: Retries for transient failures (429 / 5xx / network) (default: `2`)243- **`NBA_MCP_CACHE_TTL_SECONDS`**: Cache TTL for stats endpoints (default: `120`)244- **`NBA_MCP_LIVE_CACHE_TTL_SECONDS`**: Cache TTL for live endpoints (default: `5`)245- **`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`.246247Example Claude Desktop config:248249```json250{251 "mcpServers": {252 "nba-stats": {253 "command": "uvx",254 "args": ["nba-stats-mcp"],255 "env": {256 "NBA_MCP_LOG_LEVEL": "INFO",257 "NBA_MCP_MAX_CONCURRENCY": "8",258 "NBA_MCP_CACHE_TTL_SECONDS": "120",259 "NBA_MCP_LIVE_CACHE_TTL_SECONDS": "5",260 "NBA_MCP_RETRIES": "2",261 "NBA_MCP_HTTP_TIMEOUT_SECONDS": "30"262 }263 }264 }265}266```267268## Data Sources269270This server uses official NBA APIs:271- **Live Data API** - Real-time scores and game data272- **Stats API** - Player stats, team info, historical data273- **Schedule API** - Full season schedule including future games274275## Development276277### Running Tests278```bash279uv sync --all-extras280uv run pytest281uv run pytest --cov=nba_mcp_server --cov-report=html282```283284### Code Quality285```bash286uv run ruff check src/287uv run ruff format src/288```289290### Security (Bandit)291292Static security analysis:293294```bash295uv sync --all-extras296uv run bandit -c pyproject.toml -r src/297```298299## Releasing to PyPI300301This project uses Hatchling for builds. Recommended release steps:302303```bash304# 1) Ensure clean env + tests305uv sync --all-extras306uv run pytest307uv run ruff check src/ tests/308uv run bandit -c pyproject.toml -r src/309310# 2) Build distributions311uv run python -m build312313# 3) Upload314uv run twine upload dist/*315```316317Tip: for TestPyPI uploads, use `twine upload --repository testpypi dist/*`.318319## Requirements320321- Python 3.10+322- mcp >= 1.0.0323- httpx >= 0.27.0324325## License326327MIT License - see LICENSE file for details.328329## Contributing330331Contributions welcome! Please submit a Pull Request.332333## About the Author334335>This project was created by **Du'An Lightfoot**, a developer passionate about AI agents, cloud infrastructure, and teaching in public.336>337>Learn more and connect:338>- 🌐 Website: [duanlightfoot.com](https://duanlightfoot.com)339>- 📺 YouTube: [@LabEveryday](https://www.youtube.com/@LabEveryday)340>- 🐙 GitHub: [@labeveryday](https://github.com/labeveryday)341
Full transparency — inspect the skill content before installing.