EuroLeague Analytics

A validated data warehouse and Model Context Protocol (MCP) server for EuroLeague and EuroCup basketball, exposing precision play-by-play possessions, lineup on/off splits, four factors, and court shot charts directly to AI language models.

The Remotion launch video, micro-clips and social cards are maintained in the separate launch media repository. The deployable website remains in this repository under site/.

1. What This Is (and Why It Exists)

This is not an API wrapper. Thin wrappers already exist and provide little analytical depth.

The value of this project lives entirely in its precision derived layer:

• Exact Possessions: Counted independently from the event stream across five verified possession-ending criteria, avoiding inaccurate box-score estimation formulas (e.g. FGA - ORB + TO + 0.44*FTA).

• 5-Man Lineup Tracking: Reconstructs substitution batches dynamically to maintain exactly five players on court at all times, computing lineup-level offensive, defensive, and net ratings.

• On/Off Impact Splits: Measures team performance differential with any player on court versus on the bench.

• Court Shot Coordinates: Links spatial half-court coordinates to individual play-by-play field goal attempts, lineups, and game margins (free throws and null sentinels cleanly excluded from spatial calculations).

• Dynamic Clutch Filtering: Clutch state is preserved as margin_at_start and seconds_remaining_at_start on every possession, allowing callers to query any clutch definition dynamically.

Related MCP server: vbl-mcp

2. Verified Data Integrity & Invariants

Every number published by this warehouse is mechanically verified against official box scores and strict invariants before shipping:

3. The 14 MCP Tools

The server exposes 14 read-only tools designed specifically for LLMs. Every response declares its data coverage, quarantined game exclusions, and whether minutes are raw or corrected.

4. Generic MCP Client Setup

The server remains a standard MCP server. The hosted and local transports publish the same 14 tools, input schemas, output schemas, and safety annotations. No ChatGPT-specific metadata is present in the tool registry.

Hosted Streamable HTTP (recommended)

Use this endpoint in any MCP client that supports remote Streamable HTTP:

https://euroleague-analytics-mcp.fly.dev/mcp

For clients that use a JSON MCP configuration, the shape is:

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

The hosted endpoint uses OAuth. The client should follow the authorization discovery advertised by the server.

Local stdio

Clone the repository, configure your PostgreSQL connection string in .env, and point Claude Desktop to the local script:

{
  "mcpServers": {
    "euroleague-local": {
      "command": "python",
      "args": ["/path/to/euroleague-analytics/scripts/mcp_server.py"]
    }
  }
}

This stdio configuration is suitable for Claude Desktop and other local MCP clients. Cursor, Windsurf, Gemini/Antigravity, Codex, and custom MCP clients can use either transport when they support it. Client-specific configuration screens differ, but the server URL, tool names, and contracts do not.

For troubleshooting, see the Support & Connection Guide.

5. ChatGPT Setup

ChatGPT uses the same hosted MCP endpoint. There is no separate ChatGPT API and no fork of the tool registry.

1. In ChatGPT, open Settings → Security and login and enable Developer mode.

2. Open ChatGPT Plugins.

3. Add a new MCP connection and enter https://euroleague-analytics-mcp.fly.dev/mcp as the public Streamable HTTP URL.

4. Complete the OAuth sign-in.

5. Review the discovered 14 tools and start a new conversation with the connection enabled.

Developer mode availability can depend on the ChatGPT account and workspace policy. The current official flow is documented in OpenAI's Connect and test your plugin guide.

OpenAI public directory submission

OpenAI's current documentation redirects the former Apps SDK/App Directory material to the Plugins documentation. An MCP-only submission is supported and custom UI is optional. This repository therefore keeps the integration deliberately thin:

• all three standard safety annotations are explicit on every tool;

• every structured result is described by the existing shared response-envelope schema;

• the portable registry contains no openai/* fields or ChatGPT-only _meta values;

• OPENAI_APPS_CHALLENGE_TOKEN optionally exposes the exact domain-verification response at /.well-known/openai-apps-challenge; when unset, that route does not exist;

• no custom UI resource is registered because all workflows are complete through normal MCP tool results.

Before submission, the publisher must still complete the external portal work: identity verification, listing copy and assets, privacy/terms/support URLs, five positive and three negative test cases, country availability, OAuth details, a live Scan Tools run, and domain verification. See OpenAI's submission guide and MCP review requirements.

6. Architecture

                                  live.euroleague.net API
                                             |
                         [Scheduled GitHub Actions Pipeline]
                                             |
                +----------------------------+----------------------------+
                |                                                         |
     Immutable Response Archive                                PostgreSQL Database
   (Supabase Storage ~118 MB gzip)                         (Supabase / Frankfurt EU)
                |                                                         |
         Audit & Checksums                                    Raw & Derived Tables
                                                                          |
                                                               Security-Invoker Views
                                                                          |
                                                              Hosted / stdio MCP Server
                                                                          |
                                                            Language Models (Claude, etc.)

• Daily Live Pipeline: Automated fetch, incremental load, derived rebuild, and settlement re-checks running on GitHub Actions (.github/workflows/e2026-live.yml).

• View-Driven Query Layer: MCP queries execute against seven optimized security-invoker views. Server execution runs in under 90 ms for lineup on/off leaderboards and under 1 ms for clutch possession filters.

• Zero Hallucination Invariants: Games exhibiting unresolvable timing anomalies are quarantined in game_quality and disclosed on every query.

7. Development & Testing

Python >= 3.14 is required.

# Set up virtual environment
python -m venv .venv
.venv/Scripts/pip install -r requirements-dev.txt   # Linux/macOS: .venv/bin/pip
.venv/Scripts/pip install -e .

# Run offline unit and integration tests (1,190+ tests, no network required)
.venv/Scripts/pytest

# Run linter and formatter
.venv/Scripts/ruff check .
.venv/Scripts/ruff format --check .

8. Dual-Path Evaluation Suite

evaluation.xml contains 10 complex, realistic questions designed to test LLM retrieval and reasoning over basketball data.

tests/test_phase_8_evaluations.py re-earns every published answer along two independent paths on demand:

1. Ground-truth SQL queries executed directly against warehouse tables.

2. The exact sequence of el_* MCP tool calls an LLM would execute.

Both paths must agree with the published <expected_answer>.

9. Links & Documentation

• Landing Website: euroleague.egemenyucelen.me

• Privacy Policy: euroleague.egemenyucelen.me/privacy.html

• Support & FAQ: euroleague.egemenyucelen.me/support.html

• Sponsorship One-Pager: docs/SPONSOR_ONE_PAGER.md

• Scope of version 1: docs/SCOPE.md — what the fourteen tools do, what is left out on purpose, and why

• Decision Log: DECISIONS.md

• Phase Reports: docs/

10. License

Open source under the MIT License.