Support & Connection Guide

This guide walks through configuring your AI assistant or development environment to query EuroLeague Analytics via the Model Context Protocol (MCP).

1. Connecting with Claude Desktop

To allow Claude Desktop to use EuroLeague Analytics tools, edit your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Hosted Cloud Server (Recommended)

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

Local Server via stdio (Developers)

If you have cloned the repository and configured a local .env with your PostgreSQL connection:

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

2. Connecting with Other MCP Clients (Cursor, Windsurf, etc.)

Configure an HTTP/SSE remote MCP server using:

• Server URL: https://euroleague-analytics-mcp.fly.dev/mcp
• Transport: StreamableHTTP / SSE

3. Available Tools & Usage

The server exposes 11 read-only tools prefixed with el_. Every query response includes metadata declaring data coverage and whether minutes are raw or corrected.

• el_describe_warehouse — Start here. Discloses loaded seasons, game counts, and any quarantined games.
• el_find_games — Search games by season (e.g. E2024, E2025), team, round, date, or winner.
• el_get_boxscore — Retrieve official box score statistics for both teams and all active players.
• el_get_play_by_play — Source-ordered event stream with 5-man on-court lineups, clock readings, and margin.
• el_get_shot_data — Court shot attempts with normalized coordinates (X, Y) for spatial charting.
• el_get_team_stats — Four Factors (eFG%, TOV%, ORB%, FTR), offensive rating, defensive rating, and pace.
• el_get_player_stats — Player per-game and per-100 possession statistics.
• el_get_lineup_stats — 5-man lineup ratings, possession counts, and net differentials.
• el_get_player_on_off — Team offensive and defensive ratings with a player on court vs off court.
• el_get_possessions — Exact possession records with start score, duration, ending reason, and clutch filters.
• el_get_game — One game's score, pace, Four Factors, possession totals, and quality flags.

4. Frequently Asked Questions

What loaded seasons are currently available?

The public warehouse contains complete regular season and playoff data for E2024 (330 games) and E2025 (402 games), plus schedule and roster data for the upcoming E2026 season.

Why do responses declare "corrected" vs "raw" minutes?

In 32 specific overtime substitution events across 330 games, the source API clock recorded substitutions 60 seconds off. Our narrow, validated correction restores exact second-level agreement with the official box score (99.54% match). To ensure full transparency, every tool response explicitly declares its time basis.

What is a "quarantined" game?

When source play-by-play events contain unresolvable recording errors (such as missing possession-ending events that exceed our conservative 2-possession tolerance), those games are flagged in game_quality and excluded from default aggregations. They can still be queried by passing include_quarantined=True.

5. Troubleshooting

• Server returns 401 Unauthorized: Ensure your OAuth client token has not expired and specifies the correct audience URL.
• Connection timeout: Hosted instances wake up automatically from standby; cold starts may take 1-2 seconds on the initial request.
• Query returns empty result: Verify season codes (e.g. E2024, E2025) and 3-letter team codes (e.g. IST for Anadolu Efes, FBB for Fenerbahce, RMD for Real Madrid, PAO for Panathinaikos). Use el_find_games to inspect codes.

6. Bug Reports & Feedback

Found an anomaly in the data or want to request a new analytics feature?

• Open an issue on GitHub: github.com/egemeny13/euroleague-analytics/issues
• Direct contact: [email protected]