worldcup-mcp
This server provides live 2026 FIFA World Cup data via MCP tools:
get_group_standings— Retrieves live standings for all 12 groups (A–L), including team stats (played, won, drawn, lost, goals, goal difference, points, rank), aconfidenceflag (confirmed,likely,open), and freshness metadata (stale,fetchedAt).get_round_of_32— Retrieves the 16 Round-of-32 bracket matches with official bracket positions, showing each slot as either decided (team name, code, confidence) or undecided (eligible groups), plus best-third-place allocation logic.get_knockout_results— Obtains knockout stage results (Round of 16, Quarterfinals, Semifinals, Third Place, Final), including match status (scheduled, live, finished), scores, and winners.
General capabilities:
Integrates with Claude Desktop or Cowork HTML artifacts via MCP stdio protocol
60-second data cache with a stale last-good fallback (no crashes if the upstream API fails)
Supports two data providers:
football-data(recommended) andthesportsdb; requires a free API token for live data — without one, returns an all-undecided bracket marked asstale
Provides tools for fetching live 2026 FIFA World Cup group standings, round-of-32 bracket, and knockout results.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@worldcup-mcp what are the current group A standings?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
worldcup-mcp
A local MCP server (stdio) exposing live 2026 FIFA World Cup group standings and a Round-of-32 bracket, so a Cowork HTML artifact can call it on page load and render current data.
TypeScript (strict), Node ≥ 20,
@modelcontextprotocol/sdkover stdio.Provider abstraction (
StandingsProvider) + 60s cache +stalelast-good fallback.Pure-logic layer (third-place ranking, best-third allocation, confidence) is fully unit-tested.
Status: the server is complete and its logic/handshake tests pass offline. The live data gate is unmet until you add a free API token — see
DATA_SOURCE.md. Without a token the tools return an all-undecided bracket markedstale(no faked standings).
1. Install
cd worldcup-mcp
npm install
cp .env.example .env # then edit .env (see below)Related MCP server: mcp-claudinho
2. Environment
Var | Purpose |
|
|
| free token from https://www.football-data.org/client/register |
|
|
Get the free football-data token (instant email), put it in .env:
PROVIDER=football-data
FOOTBALL_DATA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxx3. Scripts
npm run dev # run the server from source (tsx) over stdio
npm run build # tsc -> dist/
npm start # node dist/server.js
npm test # vitest — pure-logic unit tests (no network)
npm run verify # LIVE smoke test: one real fetch, prints 12 tables + 16 R32 slots, asserts
npm run handshake # builds, launches server over stdio, lists+calls both tools, validates shapes4. Tools & output contracts
get_group_standings
Returns an object keyed by group letter A–L; each value is an array ordered rank 1→4 of
{ name, code, played, won, drawn, lost, goalsFor, goalsAgainst, goalDifference, points, rank, confidence }. confidence ∈ confirmed | likely | open (see classifier below). The object also
carries stale and fetchedAt alongside the letter keys.
get_round_of_32
Returns { matches: [...16], stale, fetchedAt }. Each match:
{ match, posA, posB, slotA, slotB }, where a slot is either
{ posCode, decided:true, team:{name,code,confidence} } or
{ posCode, decided:false, eligibleGroups:[...] }.
Bracket positions are fixed (from the official draw); only the teams change. Position map is in
src/logic/bracket.ts.
Resolution rules
Rank (1x/2x) slot:
decided:truewith the current holder of that exact rank once the group has begun, carrying itsconfidence;decided:falsewitheligibleGroups:[group]before any game.Best-third slot: stays
decided:false(with the 5-group pool) until the group stage is complete; then the top-8 thirds are ranked by points → goal difference → goals scored and allocated to slots honoring each slot'seligibleGroups.
get_knockout_results
Returns { rounds, stale, fetchedAt } where rounds is { r16:[…8], qf:[…4], sf:[…2], third:[…1], final:[…1] }. Each match: { match, posA, posB, slotA, slotB, status, score, winnerCode }:
slotA/slotBmirror theget_round_of_32shape:{ posCode, decided:true, team:{name,code,confidence} }once the feeding match is finished, else{ posCode, decided:false, feeder }(a label like"R32 M12"/"R16 #89").status∈scheduled | live | finished;scoreis{ a, b, duration?, penalties? }ornull;winnerCodeis set only whenstatus === "finished".Bracket wiring is ours (the official 2026 map: R32 ties M1..M16 feed forward as consecutive pairs → R16 → QF → SF → final); results are overlaid from the live source by matching teams. Match numbers use the official 89–104. See
src/logic/knockout.ts.Real winners propagate: a slot fills as soon as its feeding match is finished, otherwise it stays a placeholder. If the provider can't supply knockout data, every node is a placeholder +
stale.
confidence classifier
confirmed = mathematically locked at the exact rank (every other team is clearly above or clearly
below given remaining fixtures; reachable-point ties count as not-yet-separated, so it never
over-claims). likely = currently in a qualifying slot (rank 1–2) but not locked. open = otherwise.
Once every team in a group has played all 3 games, all four are confirmed.
5. Cowork / Claude Desktop integration
Register this server under the slug worldcup so the tools resolve to the names the artifact
expects:
mcp__worldcup__get_group_standingsmcp__worldcup__get_round_of_32mcp__worldcup__get_knockout_results
These are already the defaults in artifact/wc2026_bracket.html
(TOOL_STANDINGS / TOOL_RO32 / TOOL_KO). If you register under a different key, update those
constants. The artifact renders the live R32 + a projected bracket, and overlays real knockout
results from get_knockout_results once matches are played (green "result" boxes with scores;
muted boxes remain projections).
MCP config block (Claude Desktop claude_desktop_config.json → mcpServers, or the Cowork MCP
config). Use the built entry for stability:
{
"mcpServers": {
"worldcup": {
"command": "node",
"args": ["C:\\Users\\U\\OneDrive\\worldcup-mcp\\dist\\server.js"],
"env": {
"PROVIDER": "football-data",
"FOOTBALL_DATA_TOKEN": "your-free-token"
}
}
}
}(Run npm run build first so dist/server.js exists. For a no-build dev setup, use
"command": "npx", "args": ["tsx", "C:\\Users\\U\\OneDrive\\worldcup-mcp\\src\\server.ts"].)
Freshness for the artifact's "Live / stale" banner: football-data.org refreshes tables within ~1–5 minutes of a match finishing (it is not a per-second live feed). Expect "Live" right after a refresh and "stale" only if the provider call fails (then last-good is served).
6. Manual FIFA cross-check
To eyeball that live numbers are real and current, compare one group against the official source:
# Group A table straight from the provider (needs your token):
curl -s -H "X-Auth-Token: $FOOTBALL_DATA_TOKEN" \
"https://api.football-data.org/v4/competitions/WC/standings" \
| npx --yes node-jq '.standings[] | select(.group=="GROUP_A") | .table[] | {pos:.position, team:.team.name, pld:.playedGames, pts:.points, gd:.goalDifference}'Then open the official FIFA standings page for the 2026 World Cup
(https://www.fifa.com/fifaplus/en/tournaments/mens/worldcup/canadamexicousa2026) and confirm the
played/points/GD for Group A match. npm run verify performs the structural half of this check
automatically (groups, team counts, codes vs. the official draw).
7. Known limitations
Best-third allocation method. FIFA publishes a fixed lookup table keyed by which 8 of 12 groups produce a qualifying third (C(12,8)=495 rows). Rather than embed that table verbatim, this server solves the same constraint it encodes — a deterministic eligibility-honoring bipartite matching (see
src/logic/thirdPlace.ts). Every group always lands in an eligible slot; for some of the 495 combinations the exact group→slot pairing may differ from FIFA's printed table while staying eligibility-correct. Swap in the literal table here if you need byte-for-byte parity with FIFA's published bracket.Free data sources are credential-gated or capped — see
DATA_SOURCE.md. Nothing is hardcoded; absent a credential the bracket is all-undecided +stale.
8. Layout
src/
draw.ts official group draw + name→code mapping (validation only)
types.ts shared types
cache.ts 60s TTL + last-good stale fallback
service.ts provider selection, enrich(), the two tool entry points
server.ts MCP stdio server (registers the two tools)
verify.ts live smoke test
env.ts local .env loader
providers/
types.ts StandingsProvider interface (the swap seam)
footballData.ts primary provider
theSportsDb.ts secondary provider (capped on free tier)
logic/
confidence.ts confidence classifier
thirdPlace.ts third-place ranking + best-third allocation
bracket.ts fixed R32 position map + resolution
test/ vitest unit tests (confidence, thirdPlace, bracket)
scripts/handshake.ts MCP stdio handshake testAvailable Tools
2 toolsget_group_standings2026 WC group standingsA
Live 2026 FIFA World Cup group standings, keyed by group letter A–L. Each value is an array ordered by rank with played/points/GD and a confidence flag (confirmed | likely | open). Includes stale/fetchedAt.
Inputs: no named parameters.
get_round_of_322026 WC Round of 32 bracketA
The 16 Round-of-32 matches with fixed bracket positions. Each match has posA/posB labels and slotA/slotB that are either decided (with team) or undecided (with eligibleGroups). Includes stale/fetchedAt.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one for group standings and one for the round of 32 bracket. There is no overlap, so an agent can easily differentiate them.
Both tools follow the consistent 'get_<noun>' naming pattern (get_group_standings, get_round_of_32), providing a predictable and uniform interface.
With only 2 tools, the server feels under-scoped for a comprehensive World Cup data service. While the tools are relevant, additional tools for match details or team info would be expected.
The server covers only group standings and the round of 32 bracket, missing critical features like match results, team information, player stats, and later knockout stages. Significant gaps exist for a full World Cup data server.
Maintenance
Related MCP Connectors
Read-only, no-auth MCP server over Human x AI's Content Hub and confirmed 2027 facts.
This MCP server provides seamless access to Malaysia's government open data, including datasets, w…
Hosted MCP server for live public-data APIs and Skills for AI agents.
Live status and 30-day reliability of public MCP servers, from independent hourly probes.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for FIFA World Cup 2026 data: matches, teams, venues, city guides, fan zones, visa info, injuries, odds, standings, bracket, and historical matchups. 18 tools, zero external API dependencies.18176 npm33MIT
- AlicenseAqualityAmaintenanceClaudinho gives any MCP client live 2026 World Cup scores, fixtures, group standings, read-only prediction-market signals (Polymarket, informational only), and ready-to-paste match cards. Key-free; the schedule is bundled offline — only live state hits ESPN. Independent fan project — not affiliated with FIFA or Anthropic.1037MIT
- AlicenseAqualityDmaintenanceFree MCP server for the World Cup 2026 Tour public schedule API. It enables AI assistants to fetch the 2026 FIFA World Cup schedule, next match, match by ID, and dataset JSON-LD without an API key.51MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that answers football questions with interactive widgets, centered on the 2026 FIFA World Cup using SofaScore API data.1-