footballcharts-mcp

Give your AI assistant football data for 93 leagues — 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 settled track record — not betting tips. Every model signal is published before kickoff and graded after; the get_track_record tool returns that ledger.

No key needed

Every tool works without an API key at 300 requests/day per IP (20/min). A free key lifts that to 5,000/day, 60/min — 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 93 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).

Use it on claude.ai (web or mobile) — nothing to install

Settings → Connectors → Add custom connector, then paste:

https://mcp.football-charts.com/mcp

That 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-mcp

Tools

Ten read-only tools. Descriptions are written for the model: when to use it, what comes back, one example. about_football_charts needs no key.

tool	use it for
about_football_charts	What this source covers and does not, how keys and seasons work, how to phrase probabilities. Call first when unsure.
list_leagues	Turn a league name into its key; see the seasons your key can read.
get_league_table	Standings, form, expected points; view=luck or goals for alternative rankings.
get_results	Finished matches with FT/HT scores and first-goal minute; filter by team, cap with last.
get_fixtures	Upcoming matches with the baseline model's calibrated probabilities across markets.
get_match	One upcoming match in full, by slug.
get_season_projection	Title / top-4 / relegation probabilities and points ranges, 10,000 simulations, daily.
get_team	One team: table row, match log, goal timing, stats.
get_goal_timing	Goals per 15-minute bin per team with peak_bins; pass team for one team.
get_track_record	The public settled ledger of every published model lean, losses included.

The model is a public baseline (Dixon-Coles). It is calibrated and it does not beat the bookmaker market; get_track_record is the proof. Per-bookmaker opening and closing odds for 91 leagues, 2020 onward, are a paid dataset at football-charts.com/data.

Changelog

• 0.5.0 — every tool has an outputSchema and returns structuredContent; descriptions rewritten from the consumer side (purpose → when to use a sibling instead → one example); get_match drops storage internals. The tool list is ~6k tokens (was ~3k) — the schemas are the cost. Two deliberate choices: list_leagues keeps its list_ prefix because it enumerates everything rather than fetching one thing, and league stays a free string rather than an enum of the 93 keys (an enum would add ~700 tokens to every tool; list_leagues resolves a name in one call). Schema leaves are untyped so that an unexpected null never 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_results ordering wording clarified (chronological, last=N keeps 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; about and list_leagues guidance updated; MCPB desktop-extension bundle (manifest.json, icon); registry isRequired: false for FC_API_KEY.
• 0.3.0 — descriptions rewritten for the model (when / returns / example); new about_football_charts orientation tool (keyless); get_rankings folded into get_league_table via view; get_goal_timing gains a team filter and peak_bins guidance; 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
FC_API_KEY	— (required)	Your API key
FC_API_BASE	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.

Cursor 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.