NBA MCP Server
Provides live access to NBA data including player lookup, career stats, team rosters, league standings, stat leaders, daily scoreboards, and game box scores.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@NBA MCP Server Show me the box score for last night's Warriors game."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
NBA MCP Server
A Model Context Protocol server that gives any MCP-compatible LLM client (Claude Desktop, Cursor, VS Code, a custom LangGraph agent) live access to NBA stats, standings, rosters, scores and box scores.
"Compare LeBron James and Kevin Durant's playoff scoring."
"Who led the league in assists in 2023-24?"
"What was the final score and top scorers of game 0042300405?"The LLM answers these by calling tools on this server — no hard-coded data, no scraping in the prompt.
Why this project exists
Most "LLM + API" demos wire one API to one chatbot with glue code. MCP replaces the glue with a protocol: write the server once, and every compatible client can use it. This repo is a small, production-shaped example of that — caching, error handling, a clean data/protocol split, tests, and two transports (stdio + HTTP).
Related MCP server: nba-stats-mcp
Tools
Tool | What it does |
| Resolve a player name → |
| Resolve a team name / city / abbreviation → |
| All 30 teams with ids |
| Career + playoff averages + season-by-season |
| Standings by conference for a season |
| Roster with position, age, experience |
| Per-game leaders (points/rebounds/assists/…) |
| Games and scores for a date (defaults to today) |
| Final score + top 5 scorers per side |
Every tool returns {"ok": true, "data": ...} or {"ok": false, "error": "..."} so
the model can recover from a bad name instead of hallucinating.
Resources
URI | Contents |
| The 30 teams with ids (JSON) |
| What each stat field means (Markdown) |
Prompts
Prompt | Arguments |
|
|
|
|
Both walk the model through calling the tools and grounding every claim in the returned numbers.
Architecture
MCP client (Claude Desktop / Cursor / LangGraph agent)
│ JSON-RPC over stdio or streamable HTTP
▼
server.py ── tool schemas (docstrings + type hints), thin error wrapping
▼
nba_client.py ── normalizes nba_api's 80-column rows into small LLM-friendly dicts
▼
cache.py ── TTL disk cache (scores 5 min, season stats 6 h, rosters 30 d)
▼
nba_api ──► stats.nba.comnba_client.py has no MCP dependency on purpose — the same layer will feed the RAG
pipeline and agents in the companion project.
Install
git clone https://github.com/SergioCastro02/nba-mcp-server
cd nba-mcp-server
python -m venv .venv && . .venv/Scripts/activate # or source .venv/bin/activate
pip install -e ".[dev]"Run
nba-mcp-server # stdio (for Claude Desktop / Cursor)
nba-mcp-server --http # streamable HTTP on http://localhost:8000/mcp
nba-mcp-server --http --host 0.0.0.0 # bind all interfaces (containers)GET /healthz returns {"status": "ok"} for load balancers and container probes.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"nba": {
"command": "nba-mcp-server"
}
}
}(Use the absolute path to the .venv binary if it isn't on your PATH.)
MCP Inspector
npx @modelcontextprotocol/inspector nba-mcp-serverEnd-to-end demo
Launches the server as a subprocess and drives it over stdio, exactly like a real client would — resolves names to ids, compares two players' playoff stats, pulls season leaders and a box score:
python examples/mcp_client_demo.pyDeploy to AWS
Terraform stack for ECS Fargate + ALB + CloudWatch in infra/.
Development
ruff check .
pytestRoadmap
resourcesfor static reference data (nba://teams,nba://glossary)prompts(scouting_report,compare_players)IaC to deploy the HTTP transport to AWS ECS Fargate — see
infra/Wire continuous deployment (OIDC + push job) and stand up a public demo URL
Publish to PyPI
This server is the tool layer for a larger project: a multi-agent NBA analysis platform (LangGraph orchestration + RAG over news/recaps + AWS Bedrock).
Data source & limits
Data comes from stats.nba.com via nba_api.
It is unofficial and rate-limited; the disk cache absorbs most repeat calls.
Not affiliated with the NBA.
License
MIT
Available Tools
9 toolsfind_playerA
Look up an NBA player by full or partial name.
Returns the player_id needed by player_career_stats, plus any other name matches.
Inputs: name (required). Returns: object
find_teamA
Look up an NBA team by name, city, or 3-letter abbreviation (e.g. 'BOS').
Returns the team_id needed by team_roster.
Inputs: name (required). Returns: object
game_boxscoreA
Box score summary for a game: final score and top 5 scorers per side.
Get game_id from scoreboard.
Inputs: game_id (required). Returns: object
league_standingsA
Final or current standings for a season, split by conference.
season is 'YYYY-YY', e.g. '2023-24'.
Inputs: season (required). Returns: object
list_teamsA
List all 30 NBA teams with their ids and abbreviations.
Inputs: no named parameters. Returns: object
player_career_statsA
Career and per-season stats for a player.
Get player_id from find_player. Returns regular-season and playoff career averages plus a season-by-season regular-season breakdown.
Inputs: player_id (required). Returns: object
scoreboardA
Games and scores for a date (defaults to today).
game_date is 'YYYY-MM-DD'.
Inputs: game_date. Returns: object
stat_leadersA
Per-game statistical leaders for a season.
stat is one of: points, rebounds, assists, steals, blocks, three_pointers. season is 'YYYY-YY'. limit is capped at 50.
Inputs: season (required), stat, limit. Returns: object
team_rosterA
Roster for a team in a given season.
Get team_id from find_team. season is 'YYYY-YY'.
Inputs: season (required), team_id (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct NBA entity or query type: player lookup, team lookup, team enumeration, player stats, standings, roster, stat leaders, scoreboard, and box score. Even the closest pair, find_team and list_teams, are clearly differentiated as search versus full list.
Tool names mix imperative verb-led forms like find_player, find_team, and list_teams with noun/resource forms like player_career_stats, league_standings, and game_boxscore. The names are readable and consistently snake_case, but the verb/noun pattern is not applied uniformly.
Nine tools is a well-scoped size for an NBA data server, covering the major stat and score queries without redundancy. Each tool earns its place in the set.
The tool set covers the core read-only NBA workflow: player and team lookup, player stats, rosters, standings, stat leaders, scoreboard, and box score summaries. Gaps such as full box score details, player game logs, or a season schedule are minor and can be worked around.
Maintenance
Related MCP Connectors
Provide detailed Pokémon data and information through a standardized MCP interface. Enable LLMs an…
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Related MCP Servers
- FlicenseAqualityDmaintenanceA 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.101-
- AlicenseBqualityDmaintenanceProvides comprehensive NBA statistics via Model Context Protocol, enabling queries for player stats, game scores, team info, and advanced analytics through natural language.2111MIT
- AlicenseAqualityDmaintenanceExposes the StatsPlus API as tools for MCP-compatible clients, enabling users to query player/team statistics, contracts, ratings, and game history via natural language.155MIT
- AlicenseAqualityDmaintenanceMCP server for NBA live data and stats, providing read-only tools to query live scores, box scores, player info, standings, and more from NBA.com.1511 npm1MIT