Model Context Protocol for Basketball Intelligence

Validated EuroLeague & EuroCup Analytics for AI Models

Not an API wrapper. A precision derived layer reconstructing exact possessions, four factors, five-man lineup on/off splits, and court shot charts from public play-by-play event streams.

Connect to Claude Desktop View Repository on GitHub

Verified Ground Truth

Every metric is mechanically proven against official EuroLeague box scores and explicit mathematical invariants.

732

Games Loaded

330 in E2024 • 402 in E2025

107,311

Reconstructed Possessions

Counted independently from 5 ending events

99.54%

Minute Precision

Exact second match with official box score

100%

Score Reconciliation

0 point mismatches across all 732 games

41,524

Verified Coordinates

E2024 field goals with real court locations

Seasons Archived

5,950+ games in immutable cold storage

The Derived Analytics Layer

Moving beyond box-score approximations to exact play-by-play event reconstruction.

⊕

Exact Possession Accounting

Traditional box score formulas (like FGA - ORB + TO + 0.44*FTA) are crude estimates. Possessions are counted directly from the event stream across five verified possession-ending criteria, preserving offensive rebound continuations and dead-ball technical free throws.

⧉

5-Man Lineup Reconstruction

Tracks substitution batches dynamically to maintain exactly five players on court at all times. Reconstructs matchup stints, lineup offensive/defensive ratings, net ratings, and on/off player impact splits.

⌖

Court Shot Coordinates

Merges coordinate sources with play-by-play event attempts, allowing models to filter shot locations by lineup unit, clutch time remaining, and game margin.

&clock;

Dynamic Clutch Filters

Clutch is stored as margin_at_start and seconds_remaining_at_start on each possession rather than a hard-coded table. Query any clutch definition (e.g. final 2 minutes ±3 points or final 5 minutes ±5 points) on the fly.

&shield;

Honest Data Integrity

When source data contains unresolvable clock anomalies or recording errors, games are explicitly quarantined (e.g. possession_gate) and disclosed in every response, never smoothed over with synthetic data.

&zap;

Fast, Read-Only MCP Server

Exposes 11 specialized, read-only tools designed specifically for LLMs. Optimized database views serve complex four-factor and on/off splits in milliseconds.

11 Specialized MCP Tools

Read-only tools providing focused answers and strict pagination to preserve LLM context windows.

el_describe_warehouse Returns loaded seasons, game counts, coverage notes, and data exclusions.

el_find_games Search and filter games by season, round, date range, team, or winner.

el_get_boxscore Official player and team box scores with raw, corrected, and official minutes.

el_get_play_by_play Source-ordered play-by-play events with on-court lineups, score margins, and clock readings.

el_get_shot_data Shot attempts with normalized half-court coordinates (X, Y), zone classifications, and event context.

el_get_team_stats Season-level Four Factors (eFG%, TOV%, ORB%, FTR), pace, offensive rating, and defensive rating.

el_get_player_stats Player per-game and per-100 possession statistics across regular season and playoffs.

el_get_lineup_stats 5-man lineup performance with possession counts, offensive rating, defensive rating, and net margin.

el_get_on_off_splits Team net performance differential with a specific player on court versus off court.

el_get_possessions Individual possessions with start score, duration, ending reason, lineup on floor, and clutch filters.

el_get_game_quality Audit trail and validation report identifying any quarantined minutes or possession anomalies.

Quickstart Setup

Add EuroLeague Analytics to Claude Desktop or any MCP-compatible environment in seconds.

1. Local Setup via stdio (Developers)

Clone the repository and add the local server configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "euroleague": {
      "command": "python",
      "args": ["/path/to/euroleague-analytics/scripts/mcp_server.py"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:[PASSWORD]@...pooler.supabase.com:5432/postgres"
      }
    }
  }
}

2. Hosted Endpoint via HTTP/SSE

Connect directly to our hosted endpoint for authenticated read-only access:

{
  "mcpServers": {
    "euroleague-cloud": {
      "url": "https://euroleague-analytics-mcp.fly.dev/mcp"
    }
  }
}

For more client setups, troubleshooting tips, and authentication details, see the Support Guide.