io.github.ddevetak/footballcharts-mcp
Tables, results, fixtures, goal timing, season projections: 93 football leagues incl. lower tiers
Open source Repository Open in the app JSON README (API)
About
Tables, results, fixtures, goal timing, season projections: 93 football leagues incl. lower tiers
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ddevetak
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.5.0
- Last push
- 2026-09-06T08:37:07Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-09-06 09:00:40
- Origin id
io.github.ddevetak/footballcharts-mcp
README
# Football data MCP server — 93 leagues, lower divisions included (Football Charts)
[](https://www.npmjs.com/package/footballcharts-mcp) [](LICENSE) [](https://registry.modelcontextprotocol.io)
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](https://www.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:
```bash
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](https://www.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](https://github.com/ddevetak/footballcharts-mcp/releases/latest)
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. 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](https://www.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.