# footballcharts-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/ddevetak/footballcharts-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/footballcharts-mcp

## Description
Tables, results, model probabilities and Monte Carlo projections for 90+ football leagues.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "footballcharts-mcp": {
    "command": "npx",
    "args": ["-y","footballcharts-mcp"]
  }
}
```

## Documentation & README

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

[![npm](https://img.shields.io/npm/v/footballcharts-mcp)](https://www.npmjs.com/package/footballcharts-mcp) [![license](https://img.shields.io/npm/l/footballcharts-mcp)](LICENSE) [![MCP registry](https://img.shields.io/badge/MCP%20registry-io.github.ddevetak%2Ffootballcharts--mcp-blue)](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.