NBA Games, Basic and Advanced Stats MCP Server

Overview

This MCP (Model Context Protocol) server provides programmatic access to recent and historical NBA game data with both basic box-score statistics and advanced analytics. It exposes a compact, JSON-first API that is designed to be consumed by model-driven agents, analytics pipelines, dashboards, and developer tooling that require fast retrieval of game contexts and player/team metrics.

The server is useful when you need a consistent, low-latency source of structured NBA game context for tasks such as prompt augmentation for LLMs, automated scouting reports, performance trend analysis, or powering fantasy-sports tools. By packaging game data and derived advanced stats behind a small protocol surface, the MCP server simplifies integrating sports context into downstream applications.

Features

• RESTful endpoints designed for MCP-style tooling and model integration
• Access to recent and historical games, including box scores and play-level context
• Basic statistics (points, rebounds, assists, minutes, etc.)
• Derived/advanced metrics (pace-adjusted stats, shooting efficiencies, on/off splits, plus-minus)
• Query patterns for date ranges, teams, players, and game ids
• Compact JSON responses suitable for embedding into prompts or analytics workflows
• Docker-friendly and environment-driven configuration for deployment

Installation / Configuration

Prerequisites:

• Git
• Docker (recommended) or the runtime and dependency manager used by the repository (see repository README for specifics)

Clone the repo:

git clone https://github.com/Taidgh-Robinson/nba-mcp-server.git
cd nba-mcp-server

Run with Docker (recommended):

# Build
docker build -t nba-mcp-server .

# Run (example; change env vars as needed)
docker run -p 8080:8080 \
  -e PORT=8080 \
  -e DATA_REFRESH_INTERVAL=3600 \
  -e LOG_LEVEL=info \
  nba-mcp-server

Run locally (illustrative):

# If the project uses pip / npm, see the repo README for exact commands.
# Example for Python-style project:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python server.py --port 8080

Environment variables (example):

PORT=8080
DATA_SOURCE=https://example.data.provider/api
DATA_REFRESH_INTERVAL=3600   # seconds
LOG_LEVEL=info
API_KEY=your-data-provider-key

Note: Consult the repository README for the accurate runtime/install commands and any provider-specific API keys or data licensing steps required for production use.

Available Resources

The server exposes a compact set of endpoints (example endpoints — verify exact routes in the repository):

Query examples:

• Date filtering: /games?date_from=2026-01-01&date_to=2026-01-07
• Team filtering: /games?team=LAL
• Specific game: /games/20260115-LAL-BOS

Response shape (abridged example):

{
  "game_id": "20260115-LAL-BOS",
  "date": "2026-01-15",
  "home_team": "LAL",
  "away_team": "BOS",
  "box_score": {
    "players": [
      { "player_id": "player123", "minutes": 34, "points": 28, "rebounds": 8, "assists": 5 }
    ]
  },
  "advanced": {
    "off_rating": 119.2,
    "def_rating": 106.7,
    "net_rating": 12.5,
    "ts_pct": 0.615
  }
}

Use Cases

• Prompt augmentation for LLMs: Retrieve the most recent game context (box scores + advanced metrics) to include in a model prompt for automated game recap generation or question answering about player performance.

  • Example: Fetch /games?date_from=2026-02-12&team=PHI and embed returned JSON as context for a summarization model.

• Analytics pipelines: Stream historical game data and derived advanced metrics into a data warehouse for time-series analysis (player trends, lineup impacts, and team efficiency).

  • Example: Periodically call /games with date ranges and upsert results into your analytics DB.

• Fantasy sports decisioning: Use player-level advanced stats to build models for projecting short-term performance or injury-adjusted expected points.

  • Example: Query /stats/player/{player_id}?window=7 to get rolling averages and efficiency splits.

• Agent tooling and orchestration: Integrate as an MCP tool that a multi-tool agent can call to fetch relevant game context during a reasoning or planning step.

  • Example: The agent queries /games/{game_id} to get the box score and advanced metrics before producing a scouting summary.

Getting Help and Contributing

For exact endpoints, runtime commands, and contribution guidelines, refer to the project repository: https://github.com/Taidgh-Robinson/nba-mcp-server

Open issues or pull requests in the repo for bugs, feature requests, or data-source integration improvements.