football-data-mcp

A football analytics toolkit for Claude (and similar LLM tools) — player scouting, comparisons, market-value filters, expected-goals tables, match-by-match form, team attacking profiles, match search, shot maps, and more.

Built on top of ScraperFC by Owen Seymour.

What it does

Combines player and match statistics into one dataset you can explore in conversation with Claude.

Coverage: 10 leagues · 3 seasons (2023-24, 2024-25, 2025-26) · 18,800+ player records

Season stats (one row per player per season):

Match-by-match stats (optional extra step when collecting data):

Leagues covered

All leagues include three seasons: 2023-24, 2024-25, and 2025-26.

Full = goals and minutes, full xG suite including build-up, advanced passing metrics, player ratings, and market value.

Strong = same as Full except build-up xG.

Basic = goals, minutes, player ratings, and xG-style metrics; limited advanced passing; European cups lack market value.

Market value and contract data are most complete for the eight main domestic leagues (all except Championship and the two European cups).

The 10 tools

Once connected, Claude can answer questions using 10 built-in tools (leaner responses; pass team with player names when names collide).

Season-level player data

Match-by-match analytics

Requires match data to be collected first. Works across all 10 leagues. Resolve fixtures with home team + away team + season (optional league).

Setup

Everything runs on your computer: download the stats, then connect Claude Desktop or Cursor so it can answer questions using the 10 tools.

1. Install

pip install football-data-mcp

That installs two commands you can run from any folder:

• collect-data — downloads and builds the dataset
• soccer-mcp — starts the connection Claude and Cursor use

Working on the code? Clone this repo and run pip install -e . in the project folder instead.

2. Collect the data

First-time full download takes a while (some sites open a headless browser in the background).

Stats are collected from Understat, SofaScore, ClubElo, Transfermarkt, and Capology (see CHANGELOG.md for recent pipeline changes).

The unified player file also uses the REEP (Robust Entity Exchange Protocol) crosswalk (data/reference/reep_people.csv) to link player IDs across sources when names differ — for example matching Understat season rows to SofaScore dribble/passing stats, and SofaScore IDs to EA FC / SoFIFA attributes.

collect-data

Useful shortcuts:

# Only refresh one part of the data
collect-data --sofascore-only
collect-data --understat-only
collect-data --transfermarkt-only

# Extra: league xG tables, match shots, line-ups
collect-data --understat-tables-only
collect-data --understat-matches-only

# Rebuild the merged player file from files you already downloaded
collect-data --rebuild-only
collect-data --rebuild-only --export-csv   # also write a spreadsheet copy

3. Connect Claude Desktop or Cursor

Add the data connection to your app’s config. After pip install, soccer-mcp should be on your PATH (same program as python3 -m soccer_server).

Claude Desktop (macOS config file):

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "soccer-data": {
      "command": "soccer-mcp"
    }
  }
}

Cursor — ~/.cursor/mcp.json or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "soccer-data": {
      "command": "soccer-mcp"
    }
  }
}

If the app cannot find soccer-mcp, use the full path from which soccer-mcp as "command", or:

"command": "python3",
"args": ["-m", "soccer_server"]

Quit and reopen Claude or Cursor after saving. You should see all 10 tools after step 2 has finished downloading data.

Contributing

This project builds on ScraperFC. Bug fixes to the underlying scrapers are contributed back upstream — if you find something broken in a scraper, consider opening an issue or PR there too.

For issues specific to the pipeline (collect_data package / collect-data / collect_data.py) or the MCP server (soccer_server package / soccer-mcp / python -m soccer_server), open an issue here.

Credits

• ScraperFC by Owen Seymour — the foundation this project builds on
• Data sources: Understat, SofaScore, ClubElo, Transfermarkt, Capology