World Cup Stats

An automated Python ETL pipeline that extracts FIFA World Cup player and team statistics from fbref.com into a local DuckDB warehouse, exposes it through a Model Context Protocol (MCP) server, and ships a custom Claude-powered CLI assistant so you can ask questions about the data in plain English.

Covers the 2010, 2014, 2018, and 2022 World Cups — ~2,490 players with full scoring, shooting, discipline, goalkeeping, and playing-time stats.

Architecture

fbref.com ──(soccerdata: rate-limited, cached, resumable scrape)──▶  ETL pipeline (Python)
                                                                         │  clean / flatten / load
                                                                         ▼
                                                                 DuckDB warehouse
                                                                 (players, team_tournament, …)
                                                                         │
                                                       ┌─────────────────┴──────────────────┐
                                                       ▼                                      ▼
                                              MCP server (FastMCP)                 Custom Claude-API CLI client
                                       7 read-only tools over the data       "Compare Ronaldo & Messi across all 4 WCs"

Features

• Resilient scraper — soccerdata over fbref with built-in rate-limiting, on-disk caching, and per-table fetching so a run is fully resumable.
• Analytics warehouse — staging tables modelled into clean marts: a wide players table (one row per player per World Cup) and team_tournament aggregates.
• MCP server — exposes the warehouse as 7 read-only tools (FastMCP); run_sql rejects anything that isn't a SELECT.
• Conversational assistant — a custom MCP client that wires the tools into Claude's tool-use loop for natural-language Q&A.

Tech stack

Python 3.13 · soccerdata · DuckDB · MCP / FastMCP · Anthropic Claude API (Sonnet 4.6) · prompt caching

Project layout

etl/         extract (soccerdata) → load (DuckDB) → pipeline (CLI) → model (marts)
mcp_server/  FastMCP server exposing the warehouse as MCP tools
assistant/   custom Claude-API CLI that connects to the MCP server
config.py    paths, seasons, league, stat types
data/        DuckDB warehouse + scrape cache (gitignored)

Setup

python3.13 -m venv .venv
source .venv/bin/activate
pip install --prefer-binary -r requirements.txt   # --prefer-binary avoids a cryptography source build
cp .env.example .env                               # add your ANTHROPIC_API_KEY (for the assistant only)

The scraper drives a headless Chrome via soccerdata, so Google Chrome must be installed.

Usage

Build the warehouse (scrape → load → model):

python -m etl.pipeline            # all configured World Cups
python -m etl.model               # build the players / team_tournament marts

Explore the data directly (no API key needed):

python -c "import duckdb,config; print(duckdb.connect(str(config.DUCKDB_PATH),read_only=True).sql('SELECT player,team,goals FROM players WHERE season=2018 ORDER BY goals DESC LIMIT 10'))"

Run the MCP server (stdio transport):

python -m mcp_server.server

Chat with the assistant (requires ANTHROPIC_API_KEY):

python -m assistant.cli

Then ask things like:

• "Who were the top 5 scorers in 2014?"
• "Compare Cristiano Ronaldo and Messi across all four World Cups."
• "Which goalkeeper kept the most clean sheets?"

MCP tools

list_tables · list_seasons · top_scorers · player_stats · compare_players · team_summary · run_sql (read-only)

Data notes

• Source: fbref.com (Sports Reference), used for personal, non-commercial, educational purposes via soccerdata's rate-limiting and caching.
• The World Cup competition on fbref exposes standard, keeper, shooting, playing_time, and misc player tables (no passing/defense/possession — those are league-only).
• There is no expected-goals (xG) for the World Cup, and shot counts are unavailable for the 2010 and 2014 tournaments.

License

MIT