footballcharts-mcp
Query 90+ football leagues through 10 read-only MCP tools for standings, matches, model probabilities, projections and calibration data.
Discover covered leagues, countries, league keys and available seasons.
Retrieve league tables and alternative
luck/goalsrankings.Get finished results with FT/HT scores and first-goal minutes, filtered by team or latest N.
Get upcoming fixtures with model probabilities and full match details by slug, including ratings and goal-timing histograms.
Get 10,000-run Monte Carlo season projections for title/top-4/relegation chances and points ranges.
Get team season pages and league/team goal-timing heat maps.
Check the model’s public track record/calibration over a chosen lookback window.
Use it keyless with rate limits or with an optional free API key for higher limits.
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., "@footballcharts-mcp show me the current Premier League table"
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.
Football data MCP server — 98 leagues, lower divisions included (Football Charts)
English · 简体中文 (Simplified Chinese)
Give your AI assistant football data for 98 leagues (across 44 countries) — including the lower divisions other sources skip: tables, results, fixtures, goal timing, a public baseline model and Monte Carlo season projections from football-charts.com.
FC publishes probabilities and a public calibration record — not betting tips.
Every model probability is published before kickoff and scored after; the
get_track_record tool returns that record (hit rate, Brier score, reliability buckets).
No key needed
Every tool works without an API key at 100 requests/day per IP (20/min). A free key, for personal use, lifts that to 200/day, 60/min (all keys on one email address count together) — get one in seconds:
curl -X POST https://footballcharts-backend.onrender.com/api/v1/keys/register/ \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com"}'The key (fc_...) is shown once — store it. Both tiers: all 98 leagues
(top and lower divisions, women's leagues), current + previous season,
model probabilities and daily 10,000-run Monte Carlo projections, no
betting odds (the historical odds archive is a paid dataset at
football-charts.com/data).
Related MCP server: matchday-mcp
Use it on claude.ai (web or mobile) — nothing to install
Settings → Connectors → Add custom connector, then paste:
https://mcp.football-charts.com/mcpThat is the keyless tier. With a key, paste
https://mcp.football-charts.com/fc_your_key_here/mcp instead (a connector
field accepts only a URL, so the key travels in it; keys are read-only, free
and replaceable). Clients that can send headers use
POST https://mcp.football-charts.com/mcp with Authorization: Bearer fc_….
Use with Claude Desktop — one-click extension
Download footballcharts-mcp-<version>.mcpb from the
latest release
and open it; Claude Desktop installs it. The API key field can stay empty.
Use with Claude Desktop — manual config
claude_desktop_config.json (FC_API_KEY is optional since 0.4.0):
{
"mcpServers": {
"football-charts": {
"command": "npx",
"args": ["-y", "footballcharts-mcp"],
"env": { "FC_API_KEY": "fc_your_key_here" }
}
}
}Use with Claude Code
claude mcp add football-charts -e FC_API_KEY=fc_your_key_here -- npx -y footballcharts-mcpTools
Ten read-only tools. Each description says what the tool returns.
tool | use it for |
| Summary of the source: leagues covered, what it does not hold, league-key and season formats, how to read the probabilities. |
| Every league covered (98 across 44 countries) with its key, country and seasons available. |
| Standings for one league season with form, expected points and a luck category; |
| Finished matches of one league season with full-time and half-time scores and first-goal minute; filter by |
| Upcoming matches of one league with the model's calibrated probabilities. |
| One match in full, by slug: model probabilities, team ratings and goal-timing histograms. |
| Title, top-four and bottom-three probabilities and points ranges from 10,000 simulations, refreshed daily. |
| One team's season: table row, match log, goals per 15-minute period and first-goal distribution. |
| Goals per 15-minute period for every team in a league season, with peak periods and league totals; pass |
| The model's public calibration record: hit rate, Brier score and reliability buckets. |
The model is a public baseline (Dixon-Coles). It is calibrated, and
get_track_record shows how well; it does not beat the bookmaker market. Per-bookmaker
opening and closing odds for 91 leagues, 2020 onward, are a paid dataset at
football-charts.com/data.
Changelog
0.6.0 — every answer links the football-charts.com page with the same data (
source_url);get_track_recordreturns a calibration record (hit rate, Brier score, reliability buckets); descriptions say what each tool returns, with no instructions to the model, and each tool's title is also inannotations.title; outputs drop the site-only fieldsroi_*,profit_*andgates;get_season_projectionexplains a missing projection instead of failing output validation. Same ten tools and arguments.0.5.0 — every tool has an
outputSchemaand returnsstructuredContent; descriptions rewritten from the consumer side (purpose → when to use a sibling instead → one example);get_matchdrops storage internals. The tool list is ~6k tokens (was ~3k) — the schemas are the cost. Two deliberate choices:list_leagueskeeps itslist_prefix because it enumerates everything rather than fetching one thing, andleaguestays a free string rather than an enum of the 93 keys (an enum would add ~700 tokens to every tool;list_leaguesresolves a name in one call). Schema leaves are untyped so that an unexpectednullnever fails a call; the field types are what the API returns (numbers for counts and probabilities, ISO dates,'home:away'score strings).0.4.1 — registry entry declares the hosted endpoint (
remotes) so connector directories list it;get_resultsordering wording clarified (chronological,last=Nkeeps the latest N).0.4.0 — a key is optional: the API serves keyless callers at 300/day per IP (20/min) and its 429 says how to get a free key;
aboutandlist_leaguesguidance updated; MCPB desktop-extension bundle (manifest.json, icon); registryisRequired: falsefor FC_API_KEY.0.3.0 — descriptions rewritten for the model (when / returns / example); new
about_football_chartsorientation tool (keyless);get_rankingsfolded intoget_league_tableviaview;get_goal_timinggains ateamfilter andpeak_binsguidance; one structured log line per tool call on stderr (tool, ok, ms, key prefix — never arguments).0.2.0 — hosted Streamable HTTP transport, read-only annotations, key accepted from header, path or query for registry gateways.
Things to ask
"How does the Allsvenskan title race look after this weekend?"
"When does Flamengo usually score — early or late?"
"Show me the K League table, and who's overperforming what the market expected."
"Which team in Serie B hasn't conceded in the first 15 minutes?"
"What is Football Charts' actual prediction track record this season?"
Configuration
Env var | Default | Purpose |
| — (required) | Your API key |
| FC production API | Override for self-hosted/testing |
Privacy Policy
This extension sends your tool requests (league keys, team names, seasons — never your conversation) to football-charts.com's API over HTTPS. Requests are rate-limited per IP; if you configure an API key, the key identifies your account and its usage is counted per key. No conversation content is stored. Football Charts' privacy policy: https://www.football-charts.com/privacy. Questions: contact@football-charts.com.
Terms
Free for personal and research use with attribution ("Data by football-charts.com"). No resale of the data. Commercial use of the paid tier: contact@football-charts.com.
License
MIT (server code only). The data served by the football-charts.com API remains © football-charts.com, provided under the terms at https://www.football-charts.com/developers.
Claude Code plugin
This repository is also a Claude Code plugin (plugins/football-charts/). It adds
the hosted MCP server above (no key needed) and the football-data skill:
/plugin install football-charts --marketplace ddevetak/footballcharts-mcpCursor plugin
This repository is also a Cursor plugin (.cursor-plugin/plugin.json). It adds the
hosted MCP server above (no key needed) and a football-data skill that explains
the tools and the REST API. To try it locally, copy the repository to
~/.cursor/plugins/local/football-charts, reload Cursor, and check Customize for
the Football Charts MCP server and skill.
Available Tools
10 toolsget_fixturesUpcoming fixturesCInspect
Upcoming matches of a league with FC's model probabilities (Dixon-Coles based) for HT over 1.5 and FT over 2.5. Probabilities, not betting advice.
Inputs: league (required).
get_goal_timingGoal timing heat mapAInspect
When each team in a league scores: goals per 15-minute bin per team, plus league-level stats (most active period, late-goal share).
Inputs: league (required), season.
get_league_tableLeague tableAInspect
Current standings for a league season: position, points, W/D/L, goals, goal difference, last-5 form.
Inputs: league (required), season.
get_matchMatch detailAInspect
One match by slug (country/league-slug/date-home-vs-away, as returned by get_fixtures): full model probability block across markets (1X2, over/under lines, BTTS, HT lines), team ratings, first-goal-time histograms.
Inputs: slug (required).
get_rankingsAlternative rankingsAInspect
The table re-ranked by FC's alternative views: 'luck' (luck-adjusted — who over/under-performs their underlying numbers) or 'goals' (highest-scoring matches).
Inputs: view (required), league (required), season.
get_resultsMatch resultsAInspect
Finished matches of a league season with FT/HT scores and first-goal minute, oldest first. Optionally filter by team name substring and cap the number of most recent matches.
Inputs: league (required), last, team, season.
get_season_projectionSeason projectionAInspect
Monte Carlo season projection (10,000 simulations, refreshed daily): per team the title / top-4 / relegation probability, mean final points and a 10th-90th percentile points range.
Inputs: league (required).
get_teamTeam pageAInspect
One team in a league season: table row, full match log (scores, HT, venue, outcome), goal-timing bins, first-goal distribution and per-team stats.
Inputs: team (required), league (required), season.
get_track_recordModel track recordAInspect
FC's public, settled prediction track record — every published model signal graded against real results. Transparency data: hit rates and P/L by market, no cherry-picking.
Inputs: days.
list_leaguesList leaguesAInspect
All 90+ leagues on football-charts.com with country, league key and the seasons available to your key (newest first). Call this first to resolve league keys and season strings.
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 10 tools
Each tool targets a distinct function: leagues, tables, rankings, results, fixtures, matches, projections, teams, goal timing, and track records. There is minor overlap between get_league_table and get_team (both include table position), but their broader scopes differentiate them clearly.
Names follow a consistent 'get_' prefix with descriptive nouns (e.g., get_league_table, get_fixtures). One tool uses 'list_' (list_leagues) instead of 'get_', which is a minor inconsistency but still clear. Overall pattern is predictable and readable.
Ten tools cover the core domain of football data exploration and betting analytics comprehensively without bloat. Each tool addresses a specific need from listings to deep stats, making the set well-scoped for the server's purpose.
The set covers league info, tables, alternative rankings, results, fixtures, match details, season projections, team stats, goal timing, and historical track records. A minor gap is the absence of a tool to search for teams across leagues or to get player-specific data, but the coverage is solid for a football-charts API.
Maintenance
Related MCP Connectors
Football fixtures, standings, and odds intelligence for AI agents.
Calibrated, sourced football predictions: odds, tournament sims, standings, brackets, model card.
Football match predictions, title race chances, player valuations, live scores, tables and news.
Football match predictions, title race chances, player valuations, live scores, tables and news.
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.-
- AlicenseAqualityDmaintenanceLive football/soccer data from top European leagues, enabling queries for standings, fixtures, scorers, and team comparisons via natural language.610 npmMIT
- 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