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 24 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), plus the open-source libraries people build with (kloppy, mplsoccer, socceraction, soccerdata, floodlight, fast-forward, unravelsports, and more). 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

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"]
    }
  }
}

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; The Sports DB / TSDB search thesportsdb; StatsBomb Open Data searches statsbomb.

Example queries

• "What is Opta qualifier 76?" (big chance)
• "How does StatsBomb represent shot events?"
• "Compare Opta and Wyscout coordinate systems"
• "What player ID fields does Transfermarkt expose?"
• "Does SportMonks have xG data?"
• "What event types does kloppy map to GenericEvent?"
• "How does SPADL represent a tackle?"

Indexed providers

2,371 searchable chunks across 26 providers and tools.

ESPN coverage consists of curated, dated observations of ESPN-hosted soccer endpoints, checked for eng.1 and esp.1. These observations are not an official API contract or an open-data licence. See ESPN access notes for source status and coverage notes for the tested requests and limitations.

Impect documentation is built solely from the public ImpectAPI/open-data repository — a static Bundesliga 2023/24 snapshot, representative of Impect's structure and metric definitions rather than a complete or current mirror. Impect's commercial API is deliberately not documented here. Every enum value, KPI name and field name in docs/impect/ is validated against that repository in CI (pnpm impect:truth, src/__tests__/impect-open-data-validation.test.ts). Data source: Impect; use is subject to the repository's own Terms of Use.

Documentation validation

Docs for AI agents are only useful if they are correct, and prose about an API is exactly the kind of thing that drifts or gets invented. Where a machine-readable source of truth exists, this repo checks the docs against it in CI rather than trusting them.