Skip to main content
Glama
fifa-public-api-mcp

fifa-public-api-mcp

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.

npm version CI license: MIT Node 22+ MCP

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.

Related MCP server: mcp-opensky

✨ 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

Available Tools

12 tools
get_competitionA

Get details for one FIFA competition by its idCompetition (name, organizer, type). Use search_competitions first if you only have the competition's name.

Inputs: idCompetition (required), raw, language.

get_live_matchA

Get rich detail for one match: starting lineups, substitutes, officials, attendance, and weather, plus live score and status. Works for any match state (a not-yet-started match has an empty lineup and a null score). Takes idCompetition + idSeason + idStage + idMatch.

Inputs: idMatch (required), idStage (required), idSeason (required), idCompetition (required), +2 more.

get_matchesA

List a competition's matches: fixtures, kickoff times (UTC), and final scores for a season (e.g. every 2026 World Cup game). Takes idCompetition + idSeason; narrow with idStage/idGroup. Pagination is non-functional, so pass a large count for a full list; no continuation token is returned.

Inputs: idSeason (required), idCompetition (required), raw, count, +3 more.

get_match_timelineB

Get one match's event timeline in order: goals, cards, substitutions, and other key events. Takes idCompetition + idSeason + idStage + idMatch (idMatch comes from get_matches).

Inputs: idMatch (required), idStage (required), idSeason (required), idCompetition (required), +2 more.

get_seasonA

Get one season/edition (e.g. the 2026 FIFA World Cup) by idSeason: its dates, participating member associations, host teams, and resolved crest/logo image URLs.

Inputs: idSeason (required), raw, language.

get_stadiumB

Get a stadium/venue by its idStadium: name, city, and capacity.

Inputs: idStadium (required), raw, language.

get_teamA

Get a national team or club by its idTeam: name, abbreviation, country, home city, and stadium. Surfaces idStadium so you can chain to get_stadium.

Inputs: idTeam (required), raw, language.

list_confederationsA

List the six FIFA confederations (UEFA, CONMEBOL, CONCACAF, CAF, AFC, OFC), each with its idConfederation.

Inputs: raw, language.

list_countriesB

List FIFA countries and member associations (reference data), each with its idCountry.

Inputs: raw, language.

list_seasonsA

List a competition's seasons/editions (e.g. each World Cup year), newest first, with start and end dates. Takes an idCompetition; returns the idSeason that stage, fixture, and squad lookups need.

Inputs: idCompetition (required), raw, count, language.

list_stagesA

List a season's stages, e.g. Group Stage, Round of 16, Final. Takes idCompetition + idSeason; returns the idStage used to scope fixtures and match lookups.

Inputs: idSeason (required), idCompetition (required), raw, language.

search_competitionsA

Start here. Find a FIFA competition (the FIFA World Cup, Women's World Cup, club competitions and more) by name or fragment, e.g. 'world cup'. Returns the matching competitions, each with the string idCompetition that every other tool builds on.

Inputs: name (required), raw, language.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action: competitions, seasons, matches (list, live, timeline), teams, stadiums, confederations, countries. No overlap; even search vs get vs list are clearly different.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_, list_, search_). No mixed conventions or vague verbs.

    Tool Count5/5

    12 tools cover the core entities of FIFA data (competitions, seasons, stages, matches, teams, stadiums, confederations, countries). The count feels well-scoped for the domain.

    Completeness4/5

    Covers basic CRUD-like operations for major entities. Missing player/squad data and standings, but the core workflow (find competition, list seasons, get matches, drill into a match) is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides programmatic access to comprehensive football statistics and live match data via API-Football, enabling applications to retrieve league standings, team fixtures, player statistics, and real-time match events.
      6
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Access football (soccer) data including competitions, matches, standings, and team details via the Football-Data.org API.
      95 npm
      2
      MIT