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_game — Single-game Four Factors, exact possessions, ratings, and officiating crew side-by-side.
• el_get_boxscore — Retrieve official box score statistics for both teams and all active players.
• el_get_team_stats — Season-level Four Factors (eFG%, TOV%, ORB%, FTR), pace, ORtg, and DRtg.
• el_get_player_stats — Player per-game and per-100 possession statistics.
• el_get_lineup_stats — 5-man lineup performance with possession counts, offensive, defensive, and net ratings.
• el_get_player_on_off — Team net rating differential with a specific player on court versus off court.
• el_get_possessions — Exact possession records with start score, duration, ending reason, and clutch filters.
• el_get_play_by_play — Source-ordered event stream with on-court lineups, score margins, and clock readings.
• el_get_shot_data — Court shot attempts with normalized half-court coordinates (X, Y) for spatial charting.

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, ULK for Fenerbahce, MAD for Real Madrid, PAN 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: egemenyucelen@gmail.com