Zafronix Soccer MCP

by Zafronix · npm: @zafronix/soccer-mcp · MIT-licensed

Model Context Protocol server giving Claude / Cursor / any MCP-aware agent grounded access to 29 football competitions through one install — the World Cup, the Champions League, the big-five domestic leagues + their cups, and more — plus a shared player / club / stadium graph. The model calls a tool and gets the canonical answer instead of hallucinating squads, scores, brackets, and finals.

Powered by the public Zafronix football APIs. One key works across every competition — free tier, no card.

Why

LLMs are unreliable on exact historical results, roster details (jersey numbers, DOBs, captains), knockout paths, and venue facts — especially outside the training window. This server wraps the Zafronix APIs so the model calls a tool and gets the canonical answer.

Install

npm install -g @zafronix/soccer-mcp

Then add to your MCP client config (Claude Desktop claude_desktop_config.json, Cursor, etc.):

{
  "mcpServers": {
    "zafronix-soccer": {
      "command": "npx",
      "args": ["-y", "@zafronix/soccer-mcp"],
      "env": { "ZAFRONIX_API_KEY": "zwc_pk_..." }
    }
  }
}

Get a free key at api.zafronix.com/signup. (The legacy WC_API_KEY env var is still accepted.)

Pick a competition per call

Every data tool takes a competition argument — a friendly slug like world-cup, champions-league, premier-league, la-liga, serie-a, bundesliga, ligue-1, mls. Call list_competitions for the full catalogue (slug, display name, national-team vs club, tournament vs league).

Season labelling: editions are keyed by season start year — champions-league year 2005 is the 2005‑06 season. Use list_tournaments to see the exact years a competition covers.

Tools

| Tool | What it returns | |---|---| | list_competitions | the 29 competitions + their slugs/metadata | | list_tournaments | every edition/season of a competition | | get_tournament | one edition in full — teams, groups, bracket, awards, squads | | compare_tournaments | 2–6 editions side by side | | search_players / get_player_career | player search + full career within a competition | | list_teams / get_team / get_team_roster | teams (national or club) + cross-edition records + squads | | list_stadiums / get_stadium | venues with capacity, coordinates, elevation | | list_matches / get_match | matches with scores, venue, referee, attendance | | get_standings | group tables (tournaments) or season tables (leagues) | | get_bracket | knockout bracket (knockout competitions only) | | get_trivia | curated factual nuggets per edition |

Run from source

git clone https://github.com/zafronix/soccer-mcp
cd soccer-mcp
npm install
npm run build
ZAFRONIX_API_KEY=zwc_pk_... npm start

Example prompts

• "Who won the 2019 Champions League and what was the final score?"
• "Compare the 2003‑04 and 2015‑16 Premier League title races."
• "Show me Real Madrid's Champions League final appearances."
• "Which stadiums hosted the most World Cup matches?"

License

MIT © Zafronix