Skip to main content
Glama
NBA MCP Server

NBA MCP Server

NBA MCP Server

CI Python License: MIT

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

find_player(name)

Resolve a player name → player_id

find_team(name)

Resolve a team name / city / abbreviation → team_id

list_teams()

All 30 teams with ids

player_career_stats(player_id)

Career + playoff averages + season-by-season

league_standings(season)

Standings by conference for a season

team_roster(team_id, season)

Roster with position, age, experience

stat_leaders(season, stat, limit)

Per-game leaders (points/rebounds/assists/…)

scoreboard(game_date)

Games and scores for a date (defaults to today)

game_boxscore(game_id)

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

nba://teams

The 30 teams with ids (JSON)

nba://glossary

What each stat field means (Markdown)

Prompts

Prompt

Arguments

scouting_report

player_name, focus (overall/offense/defense/playoffs)

compare_players

player_a, player_b

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.com

nba_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-server

End-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.py

Deploy to AWS

Terraform stack for ECS Fargate + ALB + CloudWatch in infra/.

Development

ruff check .
pytest

Roadmap

  • resources for 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 tools
find_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

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Provides comprehensive NBA statistics via Model Context Protocol, enabling queries for player stats, game scores, team info, and advanced analytics through natural language.
      21
      11
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Exposes the StatsPlus API as tools for MCP-compatible clients, enabling users to query player/team statistics, contracts, ratings, and game history via natural language.
      15
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      15
      11 npm
      1
      MIT