football-docs

football-docs

Searchable football data provider and tooling documentation for AI coding agents. Like Context7 for football data.

Who it's for: Developers and analysts who use AI coding tools (Claude Code, Cursor, VS Code Copilot) to work with football data. Works with any tool that supports MCP.

What it does: Gives your AI agent a searchable index of documentation for 31 football data providers and tools — event types, qualifier IDs, coordinate systems, API endpoints, data models, identity surfaces, and cross-provider comparisons for the data providers (StatsBomb, Opta, Wyscout, Impect, SkillCorner, Sportradar, TheSportsDB, FMDB Pro, TransferRoom, and more), the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, fast-forward, unravelsports, and more), and the APIs of wearable and sports-science vendors (STATSports, Firstbeat, Hawkin Dynamics, VALD). Your agent looks up the real docs instead of guessing from training data.

Why not just let the AI figure it out? LLMs get football data specifics wrong constantly — Opta qualifier IDs, StatsBomb coordinate ranges, API endpoint URLs, library method signatures. These are mutable facts that change across versions. football-docs gives the agent verified, sourced documentation with provenance tracking so you know where every answer came from.

Strategy

football-docs is intended to be a community-owned, source-transparent Context7 for football data. The public operating contract is in STRATEGY.md: what belongs here, what must stay out, how we handle public-safe provider facts, and how contributors should prove retrieval quality.

Provider identity facts

football-docs is the public source for provider identity-surface facts: access shape, ID schemes, matching fields, provider quirks, and provenance rules. Curated provider identity notes belong here when they can be stated as public facts about the provider. They should say whether a fact comes from public docs, public page evidence, licensed feed shape, or a reviewed public-safe observation, and must not include credentials, local paths, internal tooling details, or restricted payloads from any private project.

MCP (Model Context Protocol) is a standard for connecting AI coding tools to external data sources.

Quick start

The server needs Node.js 22.13 or newer. It uses Node's built-in SQLite, so no native module is compiled at install time.

Claude Code

claude mcp add football-docs -- npx -y football-docs

Cursor

Settings → MCP → Add server. Use this config:

{
  "mcpServers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

VS Code / Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "football-docs": {
      "command": "npx",
      "args": ["-y", "football-docs"]
    }
  }
}

After an update

npx updates its cached copy of football-docs in place. A server that was already running keeps the old version until it restarts, and its replies then start with a note: "football-docs on disk is now vX, but this server is still running vY". Reconnect the server to fix it (in Claude Code: /mcp, then reconnect football-docs).

Tools

Provider filters use the indexed provider keys shown by list_providers, but common aliases are accepted. Examples: fbref, understat, ClubElo, football-data.co.uk, and engsoccerdata search free-sources; Sofascore searches soccerdata; ESPN, ESPN FC, and espn-soccer search espn; FMDB searches fmdb-pro; Transfer Room searches transferroom; Hudl Wyscout searches wyscout; Stats Perform / Opta F24 / WhoScored search opta; Metrica, Sportec / DFL, and TRACAB search databallpy; Second Spectrum searches kloppy; Hawk-Eye, SciSports, Signality, Respovision, GradientSports and OptaVision search fast-forward; unravel searches unravelsports; SportRadar API / Soccer Extended search sportradar; Sonra / Apex search statsports; Hawkin searches hawkin-dynamics; ForceDecks / NordBord / ForceFrame search vald; The Sports DB / TSDB search thesportsdb; StatsBomb Open Data searches statsbomb.

How the index stays current

The package ships a docs index, but doc fixes do not wait for a new package version. Once a day at most, the server checks the data-latest release of this repository for a newer index built from main:

• It reads a small signed manifest (manifest-v1-signed.json) and, only when that names a newer build, downloads the index (about 6 MB).
• It accepts the manifest only if its ed25519 signature verifies against a public key shipped in the package (src/data-signing.ts). The manifest carries the index's size and SHA-256, so the signature covers the index too.
• It checks the download's size and SHA-256, its SQLite integrity, its exact schema and its metadata before using it, and keeps the one it had on any failure.
• It stores downloads in $XDG_DATA_HOME/football-docs/data/ (by default ~/.local/share/football-docs/data/). The next tool call uses the new file; no restart is needed.
• It runs in the background after start-up and never delays a tool call. list_providers ends with the build time of the index in use and whether it is bundled or downloaded.

Privacy: the check is one HTTPS request a day to GitHub, plus the download when there is one. No search queries or other usage data are sent.

Settings, as environment variables in the server's MCP configuration:

• FOOTBALL_DOCS_DATA=bundled: use only the index inside the package. No update check, no downloads. (This does not turn off the paper tools; see FOOTBALL_DOCS_PAPERS under Papers and web sources.)
• FOOTBALL_DOCS_DATA=auto: the default for an installed package. Check daily and use the newest valid index.
• FOOTBALL_DOCS_DB_PATH=<file>: use exactly this index file.
• FOOTBALL_DOCS_DATA_BASE_URL=<url>: read the manifest and index from a mirror (HTTPS only).

Offline, or behind a proxy that Node's built-in fetch does not use, the check fails quietly and the server keeps the index it has. Under CI (CI set) the check does not run. A server running from a git checkout defaults to bundled, so development and tests always use the working tree's docs.

Papers and web sources

Many football methods come from papers, and some from blog posts: Karun Singh introduced expected threat (xT) in a blog post, not a paper. search_papers finds papers and the works that cite an idea; a web search finds the original post, and get_web_source reads it. get_paper checks that a reference exists, read_paper reads it, and match_quote checks that a quote is in the source.

Open and paid papers

football-docs never logs in to a publisher or a library, never holds your credentials or cookies, and does not use publisher text-mining APIs (their terms exclude tools like this). When a site answers with a bot check, the tool stops; download the paper yourself instead.

Zotero: search_papers with sources: ["zotero"] searches your library, and read_paper reads an item's PDF. Two ways to connect, tried in this order:

1. Zotero on this computer. In Zotero 7, open Settings > Advanced and turn on "Allow other applications on this computer to communicate with Zotero". The tools then use its local API on port 23119; nothing leaves the machine.
2. The Zotero web API, for when Zotero is not running here (another machine, a cloud session). Create a read-only key at zotero.org/settings/keys with access to your library and its files, and set ZOTERO_API_KEY (and optionally ZOTERO_USER_ID; without it the tools ask the key). It reads only files kept in Zotero's own storage, not linked files; for those it uses Zotero's full-text index. The key is sent only to api.zotero.org, never to the file storage host.