fifa-public-api-mcp

⚽ Live FIFA World Cup & football data for your AI assistant: an MCP server for competitions, fixtures, live scores, lineups, squads, and stadiums.

Give Claude, or any Model Context Protocol client, instant read-only access to the public FIFA data API for football (soccer): every FIFA competition (the men's and women's World Cups, club competitions, and more), their fixtures and results, live match detail, and reference data. No API key, no auth, no rediscovering FIFA's undocumented endpoints. Just install and ask.

⚡ What you can ask

Once it's connected, ask your assistant things like:

• "Who's hosting the 2026 FIFA World Cup, and which stadiums are being used?"
• "List the knockout-stage fixtures for the FIFA Women's World Cup."
• "What was the final score, lineup, and attendance for that match?"
• "Which six confederations does FIFA recognise, and how many member associations are there?"

Your assistant picks the right tools and chains the FIFA IDs for you behind the scenes.

✨ Features

• ⚽ 12 read-only tools spanning competitions, seasons, stages, fixtures, results, live matches, teams, stadiums, and reference data.
• 🔑 No API key or sign-up: wraps the public FIFA API directly.
• 🌍 Localised output via a language arg, plus a raw escape hatch that returns the untouched FIFA payload.
• 📦 One-line install with npx: nothing to clone or build.
• 🛡️ Typed and tested: unit-tested response normalizers and provenance-signed npm releases.

🚀 Install

The server is published to npm and runs via npx, so there is nothing to clone or compile.

Claude Code:

claude mcp add fifa -- npx -y fifa-public-api-mcp

Claude Desktop: add this to mcpServers in your config:

{
  "mcpServers": {
    "fifa": {
      "command": "npx",
      "args": ["-y", "fifa-public-api-mcp"]
    }
  }
}

npx downloads and caches the package on first use; later runs are offline-fast. Requires Node 22+ on the PATH.

🧰 Tools

Every tool also accepts two optional args: raw (default false; return FIFA's untouched payload) and language (default en).

Tool	Inputs	Returns
search_competitions	name	[{idCompetition, name}]
get_competition	idCompetition	{idCompetition, name, owner, type}
list_seasons	idCompetition, count?	[{idSeason, name, startDate, endDate}]
get_season	idSeason	{idSeason, name, dates, memberAssociations[], hostTeams[], pictureUrls}
list_stages	idCompetition, idSeason	[{idStage, name}]
list_countries	none	[{idCountry, name}]
list_confederations	none	[{idConfederation, name}]
get_matches	idCompetition, idSeason, idStage?, idGroup?, count?	{matches:[…]} (see pagination note)
get_match_timeline	idCompetition, idSeason, idStage, idMatch	{idMatch, events:[…]}
get_live_match	idCompetition, idSeason, idStage, idMatch	{idMatch, status, score, home, away, officials, attendance, weather}
get_team	idTeam	{idTeam, name, abbreviation, country, city, stadium, idStadium, pictureUrl}
get_stadium	idStadium	{idStadium, name, city, capacity}

IDs are stable string handles chained between endpoints. A typical flow: search_competitions → list_seasons → list_stages → get_matches → get_match_timeline / get_live_match.

Example IDs (FIFA World Cup 2026): idCompetition=17, idSeason=285023. These are examples for trying the tools, not defaults baked into the server.

⚠️ Known limitations

• No standings. FIFA's /calendar/standing endpoint returns 200 null for every competition and season tested, so no standings tool ships.
• No real pagination on get_matches. The API's continuation cursor is non-functional, so count is only a single-request hard limit. Set a large count (e.g. 500) for a full fixture list, and narrow with idStage / idGroup; there is no way to page past count.
• get_live_match returns data for any match state, not just live matches. A not-started match has an empty lineup and a null score.

🛠️ Develop from source

git clone https://github.com/chrispickford/fifa-public-api-mcp.git
cd fifa-public-api-mcp
npm install
npm run build      # compiles TS to build/index.js (with shebang + executable bit)
npm test           # vitest unit tests over the normalizers (no network, CI-safe)
npm run smoke      # manual live end-to-end hit of every tool against the real API (needs network)

Point a client at the local build with an absolute path, e.g. claude mcp add fifa-dev -- node /absolute/path/to/build/index.js.

The code is four small, single-purpose layers: src/client.ts (the only module that touches the network; encodes the FIFA base-API conventions and throws a structured FifaApiError), src/shape.ts (pure, unit-tested response normalizers), src/tools.ts (tool definitions and handlers wiring client → shape), and src/index.ts (bootstrap: register tools, connect StdioServerTransport).

License

MIT © Chris Pickford