matchday-mcp
Allows access to Premier League football data including standings, fixtures, results, top scorers, and team comparisons.
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., "@matchday-mcp How's Barcelona doing in La Liga this season?"
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.
⚽ matchday-mcp
A Model Context Protocol server that gives any MCP client (Claude Desktop, Claude Code, …) live football/soccer data — standings, fixtures, results, top scorers and team comparisons across Europe's top leagues.
Built with TypeScript + Zod, backed by the free football-data.org API.
Ask Claude "How is Real Madrid doing this season?" or "Compare Arsenal and Liverpool's recent form" and it answers with real data through these tools.
🔗 Live playground: matchday-mcp-web.vercel.app — an interactive dashboard built with SvelteKit + Svelte 5 that runs on this server's data layer.
Demo
> get_standings { "competition": "La Liga" }
**La Liga standings — 2025**
# Team P W D L GD Pts
1 FC Barcelona 38 31 1 6 59 94
2 Real Madrid CF 38 27 5 6 42 86
3 Villarreal CF 38 22 6 10 26 72
4 Club Atlético de Madrid 38 21 6 11 18 69
...Related MCP server: mcp-sofascore
Tools
Tool | What it does |
| League table for a competition (position, W/D/L, GD, points). |
| Matches for a competition, filterable by status and matchday. |
| Top scorers for a competition. |
| Look up a club by name (country, stadium, founded year, competitions). |
| A club's recent results or upcoming fixtures, with a W/D/L form string. |
| Compare two clubs by recent form (last 5) and W/D/L tally. |
Competitions (free tier): Premier League (PL), La Liga (PD), Bundesliga (BL1),
Serie A (SA), Ligue 1 (FL1), Eredivisie (DED), Primeira Liga (PPL), Championship (ELC),
Brazil Série A (BSA), Champions League (CL), World Cup (WC), European Championship (EC).
You can pass a competition by name ("Premier League") or code ("PL").
Quick start (Claude Desktop)
Get a free API token at football-data.org/client/register (takes ~1 minute).
Add the server to your
claude_desktop_config.json:{ "mcpServers": { "matchday": { "command": "npx", "args": ["-y", "matchday-mcp"], "env": { "FOOTBALL_DATA_TOKEN": "your_free_token_here" } } } }Restart Claude Desktop. Ask it about standings, fixtures, scorers or team form.
Works the same in any MCP client. In Claude Code:
claude mcp add matchday -e FOOTBALL_DATA_TOKEN=your_token -- npx -y matchday-mcp.
Development
git clone https://github.com/reiorozco/matchday-mcp.git
cd matchday-mcp
npm install
export FOOTBALL_DATA_TOKEN=your_free_token # required to hit the live API
npm run dev # run the server over stdio (tsx)
npm test # run the unit tests (no token needed — fetch is mocked)
npm run typecheck # tsc --noEmit
npm run build # bundle to dist/ with tsupVariable | Required | Description |
| yes | Free token from football-data.org. |
Design notes
Zod-validated tools. Every tool input is described and validated with Zod, so the model gets clear schemas and bad arguments fail fast with readable errors.
Caching + rate-limit resilience. The free tier allows 10 req/min and returns HTTP 429 when exceeded, so the client adds an in-memory TTL cache plus bounded retry/backoff.
Lazy team index. football-data.org has no team-name search, so the client builds a name → id index across the domestic leagues one league at a time with early exit — a well-known club costs 1–2 requests, not a full sweep. Name resolution is ranked (exact → starts-with → shortest name), so
"Barcelona"→ FC Barcelona, not RCD Espanyol.Off-season aware. In the off-season the API's "current season" already points at the next, not-yet-started season (empty tables), so the default season rolls over in August.
Pure, testable handlers. Tool logic lives in plain functions returning strings; the MCP wiring is a thin layer on top. The same data layer powers the web playground (source).
Data
Data from football-data.org. This project is not affiliated with football-data.org or any league.
License
MIT © Reinaldo Orozco
Available Tools
6 toolscompare_teamsCompare two teamsA
Compare two clubs by recent form (last 5 results) and W/D/L tally.
Inputs: teamA (required), teamB (required), season.
find_teamFind a teamA
Look up a club by name across the major leagues. Returns country, stadium, founding year and competitions.
Inputs: name (required).
get_matchesGet competition matchesA
Get matches for a competition. Filter by status (SCHEDULED/FINISHED/IN_PLAY) and/or matchday.
Inputs: competition (required), season, status, matchday.
get_standingsGet league standingsB
Get the current league table for a competition (position, W/D/L, GD, points).
Inputs: competition (required), season.
get_team_matchesGet team matchesA
Get a club's matches (recent results or upcoming fixtures), with a W/D/L form string.
Inputs: team (required), limit, season, status.
get_top_scorersGet top scorersC
Get the top scorers for a competition.
Inputs: competition (required), limit, season.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools are mostly distinct, but compare_teams and get_team_matches both provide form data, which could cause slight confusion. Overall, each tool serves a clear purpose.
All tool names follow a consistent verb_noun pattern (e.g., find_team, get_matches, get_standings), with no mixing of conventions.
Six tools is a well-scoped set for a football data server, covering essential operations without being overly numerous or sparse.
Core football data (teams, matches, standings, scorers, comparison) is covered. Minor gaps include individual match details and player statistics, but the set is reasonably complete for common use cases.
Maintenance
Related MCP Connectors
Football fixtures, standings, and odds intelligence for AI agents.
Live football scores, fixtures, standings, lineups and player stats for 1400+ leagues.
Football fixtures, live scores, standings, lineups, teams and players for 117 leagues and cups
Live scores, fixtures, standings, team profiles and news for 2000+ football and basketball leagues.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceProvides tools to query football match data, odds, standings, and team statistics via natural language, integrating with the football-scraper-api.-
- FlicenseNot gradedqualityDmaintenanceProvides live football match data from Sofascore, including formations, injuries, betting odds, and league positions, enabling natural language queries about matches.1-
- FlicenseNot gradedqualityDmaintenanceEnables natural language querying of football/soccer data via the API-Football service, providing access to leagues, teams, players, fixtures, standings, and statistics.2-
- AlicenseAqualityCmaintenanceEnables AI assistants to query live football data, including fixtures, live scores, standings, statistics, betting odds, and full odds movement history for corner and card lines.1131 npmMIT