Footballcharts Mcp

io.github.ddevetakPublished by GitHub account ddevetakv0.5.0Updated Nov 2, 2026

Tables, results, fixtures, goal timing, season projections: 93 football leagues incl. lower tiers

VerifiedStreamable HTTPWeb executableLocation & LifestyleData & Analytics

Overview

AI-generated overview

Read-only football data server: league tables, results, fixtures, goal timing and model probabilities for 93+ leagues, including lower divisions.

What you can do
  • Look up leagues and season formats, and read standings with expected points and luck categories
  • Retrieve finished results and upcoming fixtures with the model's calibrated probabilities
  • Open a single match by slug with team ratings and goal-timing histograms
  • Get season projections (title, top-four, bottom-three) from daily Monte Carlo runs
  • Inspect one team's season log, goals per 15-minute period and first-goal distribution
  • Check the model's public calibration record (hit rate, Brier score, reliability buckets)
When to use it
Useful when you want an assistant to answer questions about European and other football leagues, including lower tiers and women's leagues: standings, form, scoring patterns, fixture probabilities and season outlooks, with a published accuracy record rather than betting tips.
Requirements
Runs as a hosted remote endpoint or as a local npm package via npx (Node.js). No key is required: the keyless tier allows 100 requests/day per IP. An optional free key, set as FC_API_KEY or passed in the connector URL or an Authorization header, raises limits to 200/day. Network access to the football-charts.com API is needed.
Before you install
The optional FC_API_KEY is a secret shown only once; in the URL-based connector setup it travels inside the URL, so treat that URL as sensitive. Tool requests (league keys, team names, seasons) are sent to football-charts.com over HTTPS and rate-limited per IP. Data is free for personal and research use with attribution; resale is not allowed and commercial use of the paid tier requires contacting the provider. Probabilities are a public baseline model, not betting advice.

Installation

In SourceWeft

  1. Open Footballcharts Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.ddevetak%2Ffootballcharts-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "footballcharts": {
      "type": "http",
      "url": "https://mcp.football-charts.com/mcp"
    }
  }
}

README

Football data MCP server — 98 leagues, lower divisions included (Football Charts)

[npm] [license] [MCP registry]

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:

bash
curl -X POST https://footballcharts-backend.onrender.com/api/v1/keys/register/ \  -H 'Content-Type: application/json' \  -d '{"email":"[email protected]"}'

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

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):

json
{  "mcpServers": {    "football-charts": {      "command": "npx",      "args": ["-y", "footballcharts-mcp"],      "env": { "FC_API_KEY": "fc_your_key_here" }    }  }}

Use with Claude Code

bash
claude mcp add football-charts -e FC_API_KEY=fc_your_key_here -- npx -y footballcharts-mcp

Tools

Ten read-only tools. Each description says what the tool returns.

tooluse it for
about_football_chartsSummary of the source: leagues covered, what it does not hold, league-key and season formats, how to read the probabilities.
list_leaguesEvery league covered (98 across 44 countries) with its key, country and seasons available.
get_league_tableStandings for one league season with form, expected points and a luck category; view=luck or goals for alternative rankings.
get_resultsFinished matches of one league season with full-time and half-time scores and first-goal minute; filter by team, keep the latest N with last.
get_fixturesUpcoming matches of one league with the model's calibrated probabilities.
get_matchOne match in full, by slug: model probabilities, team ratings and goal-timing histograms.
get_season_projectionTitle, top-four and bottom-three probabilities and points ranges from 10,000 simulations, refreshed daily.
get_teamOne team's season: table row, match log, goals per 15-minute period and first-goal distribution.
get_goal_timingGoals per 15-minute period for every team in a league season, with peak periods and league totals; pass team for one team.
get_track_recordThe 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_record returns 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 in annotations.title; outputs drop the site-only fields roi_*, profit_* and gates; get_season_projection explains a missing projection instead of failing output validation. Same ten tools and arguments.
  • 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 varDefaultPurpose
FC_API_KEY— (required)Your API key
FC_API_BASEFC production APIOverride 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: [email protected].

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: [email protected].

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

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.

Source: README.md at commit bef9108

Tools

10

about_football_charts

About this source

Returns a summary of the football-charts.com source: the leagues and data it covers (93 leagues, including lower divisions), what it does not hold (live scores, player data, bookmaker odds), the league-key and season-string formats, how the model probabilities are produced, and the free-tier limits. No parameters.

Takes no parameters.

list_leagues

List leagues

Returns every league covered (93 across 42 countries) with its league key, display name, country and the seasons available, newest first. Other tools take these league keys and season strings. Season format depends on the competition: '2026-2027' for winter-calendar leagues, '2026' for summer-calendar leagues. No parameters.

Takes no parameters.

get_league_table

League table

Returns the standings of one league season: one row per team with position, played, wins, draws, losses, goals, points and last-five form, plus expected points and a luck category (how far results run ahead of or behind the underlying performance). view='luck' orders the same rows by over- or under-performance and view='goals' by goals scored; the default orders by points. Without a season, returns the current season.

Parametersviewleaguerequiredseason

get_results

Match results

Returns the finished matches of one league season in chronological order: date, teams, full-time and half-time score, first-goal minute and a goalless flag. team keeps the matches where either side's name contains the given text (case-insensitive); last=N keeps only the N most recent matches. Contains no odds.

Parameterslastteamleaguerequiredseason

get_fixtures

Upcoming fixtures

Returns the upcoming matches of one league, earliest first: kick-off date and time, teams, a match slug, and the model's calibrated probabilities (home and away win, over/under goal lines, both teams to score, half-time lines; the draw probability is 1 - home - away) with team attack and defence ratings. The probabilities come from a baseline statistical model of past results (no injuries, motivation or weather) and are not bookmaker prices.

Parametersleaguerequired

get_match

Match detail

Returns one match in full, identified by its slug ('country/league-slug/YYYY-MM-DD-home-vs-away', as listed in the slug field of upcoming fixtures): the complete model probability block (calibrated and raw), team ratings, first-goal-time histograms for both sides, recent form and, once played, the score, half-time score and status.

Parametersslugrequired

get_season_projection

Season projection

Returns how one league's current season is projected to finish, from 10,000 Monte Carlo simulations refreshed daily: for each team the probabilities of winning the title, finishing in the top four and finishing in the bottom three, current points, mean final points, a 10th-90th percentile points range, a finishing-position matrix, and the change since the previous run. Covers the current season only; returns a note when no projection exists for the league yet.

Parametersleaguerequired

get_team

Team page

Returns one team's season in one league: its table row (with expected points and luck category), the full match log (date, opponent, home or away, score, half-time score, first-goal minute, outcome), goals per 15-minute period, the first-goal distribution, and season averages of match statistics (shots, shots on target, possession, corners, xG) where the league has them. team is a lower-case slug with hyphens, e.g. 'arsenal' or 'manchester-city'.

Parametersteamrequiredleaguerequiredseason

get_goal_timing

Goal timing

Returns goals per 15-minute period (0-15 to 90+) for every team in one league season, with each team's peak period or periods (ties are listed together), share of late goals and share of first-half goals, plus league totals and the league's most active period. team limits the result to teams whose name contains the given text.

Parametersteamleaguerequiredseason

get_track_record

Model calibration record

Returns the public calibration record of the model: every probability published before kick-off and scored after the result, with count, hit rate, Brier score and reliability buckets (predicted probability against observed frequency), overall and by question type (match result, total goals over 2.5 and 3.5, half-time goals over 1.5, both teams to score), plus the 50 most recent scored predictions. Misses are included. days sets the lookback window (default 90).

Parametersdays

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts