football-data-mcp 0.3.0

Football data pipeline, MCP server tools, and pluggable storage for soccer analytics.

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):

Kind of data	Where it’s available
Goals, assists, minutes, shots, cards	All 10 leagues
Expected goals (xG), expected assists (xAG)	All 10 leagues — Understat model in top five; SofaScore model elsewhere (xg_source / xag_source columns)
Non-penalty xG, build-up xG, xG chain	Top five leagues only (Understat; not comparable to SofaScore xG)
Advanced passing & chance creation	Top five + Netherlands + Portugal — not Championship or European cups
Player ratings, duels, dribbles, big chances, and 80+ other performance metrics	All 10 leagues
Market value, contract end date, height, nationality	Domestic leagues — weakest for Champions League and Europa League

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

Kind of data	Where it’s available
Last N games, form, ratings, shot locations, team xG for/against	All 10 leagues (after match data is collected)
League tables ranked by xG (home / away / overall)	Top five leagues only

---

Leagues covered

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

League	Season-level data	Match-by-match
England Premier League	Full — xG, build-up, advanced passing, ratings, market value	Yes
Spain La Liga	Full	Yes
Germany Bundesliga	Full	Yes
Italy Serie A	Full	Yes
France Ligue 1	Full	Yes
Netherlands Eredivisie	Strong — xG, advanced passing, ratings, market value (no build-up xG)	Yes
Portugal Primeira Liga	Strong	Yes
England EFL Championship	Basic — ratings and core stats; lighter xG; market value often available	Yes
UEFA Champions League	Basic — ratings and core stats; no market value	Yes
UEFA Europa League	Basic — ratings and core stats; no market value	Yes

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

Tool	What you can ask
get_player	"Show me Salah's season stats" (defaults to All Competitions row)
get_eafc_player_attributes	"What are Saka's EA FC pace and shooting ratings?"
scout_position	"Top 10 forwards in the Bundesliga by goals" (use position codes F/M/D/GK)
compare_players	"Compare Salah 2024-25 vs Haaland 2025-26" (per-player season in subjects)
get_team_stats	"Arsenal's league table and average xG this season" (defaults to All Competitions)
compare_teams	"Compare Liverpool and Man City on standings and xG" (each team can use a different season)

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).

Tool	What you can ask
get_match	Lean overview: score, possession, xG, shots, big chances for one fixture
get_match_player_stats	All players in one match — ratings, goals, xG per player
get_player_match_stats	One player over a date range or matchdays — pass start_date/end_date or match_days; optional include_summary for form aggregates
get_match_shots	Shot map for a match; add player to filter to one player's shots

---

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