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

Every tool returns {"ok": true, "data": ...} or {"ok": false, "error": "..."} so the model can recover from a bad name instead of hallucinating.

Resources

Prompts

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