football-data-mcp 0.2.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), non-penalty xG, expected assists	All 10 leagues — richest in the top five European leagues
Build-up xG (how much a player contributes before a shot)	Top five leagues only (England, Spain, Germany, Italy, France)
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 16 tools

Once connected, Claude can answer questions using 16 built-in tools.

Season-level player data

Tool	What you can ask
get_player	"Show me everything on Bukayo Saka"
scout_position	"Top 10 forwards in the Bundesliga this season by xG"
compare_players	"Compare Salah and Son across all stats"
find_similar_players	"Find players similar to Bellingham under €80m"
get_league_table	"xG league table for Serie A, home games only" (top five leagues)
get_match	Shot map and line-ups for a specific match (top five leagues)
get_sofascore_match	Deep stats for one fixture — players, teams, shots
get_club_elo	"How strong is Real Madrid right now?"
get_player_history	Market value over time or transfer history for a player
data_status	What data you have loaded and how complete it is

Match-by-match analytics

Requires match data to be collected first. Works across all 10 leagues.

Tool	What you can ask
get_player_match_log	"Salah's last 10 Premier League matches with ratings and xG"
get_player_form	"Haaland's average rating and xG per 90 over recent games"
get_team_stats	"Arsenal's average xG for and against this season"
compare_teams	"Compare Liverpool and Man City on xG and possession"
search_matches	"High-xG Premier League games this season"
get_player_shot_map	"Shot locations and xG for Kane in the Bundesliga"

---

Setup

Everything runs on your computer: download the stats, then connect Claude Desktop or Cursor so it can answer questions using the 16 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):

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 16 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: FBref, SofaScore, Understat, Transfermarkt