io.github.ddevetak/footballcharts-mcp

What football-charts.com covers (93 leagues incl. lower divisions), what it does NOT hold (live scores, players, odds), how league keys and season strings work, how to phrase model probabilities honestly, and which tool answers what. Call when unsure whether this source fits a question, or once before the first call in a session. No parameters. Example: "Can you get me Estonian league data?" → about_football_charts, then list_leagues.

Upcoming matches of one league, earliest first: kick-off date and time, teams, a slug, and the model's calibrated probabilities (home/away, over/under ladders, both teams to score, half-time lines; draw = 1 − home − away) with team attack/defence ratings. Use for "who plays this weekend", kick-off times, or the chances in an upcoming match. The slug on each row is the input to get_match, which returns one fixture in full — call this first when you need one match in depth. Use get_results for matches already played. Probabilities are a baseline model from match history alone (no injuries, motivation or weather) and are not market prices or advice — say so. Example: "What are the chances of goals in Brentford v Sunderland?" → get_fixtures premier, read model_predictions.dc_v2.calibrated["over_2.5"].

Goals per 15-minute bin (0-15 … 90+) for every team in a league season, each with peak_bins (the bin or bins with most goals — ties are listed; report a tie as a tie), late_share_pct and first_half_pct, plus league totals and the most active period. Use for "when does X score", late goals, fast starters, who concedes early, or which period a league's goals fall in. Pass team (name substring) for one team only. For one team's timing next to its match log get_team is more direct. Answer from peak_bins, never by eyeballing the bins. Example: "When does Flamengo score most?" → get_goal_timing brazil1, team="Flamengo".

Standings for one league season: one row per team with position, played, W/D/L, goals, points, last-five form, plus expected points and a luck category (how far results run ahead of or behind the underlying numbers). Use for "who is top", "how many points", "what is the form", or any question about the table as ranked by points. view="luck" re-orders the same rows by over/under-performance (who is lucky, unlucky, flattered by the table); view="goals" by scoring. For one team in depth use get_team; for how the season is projected to END use get_season_projection. Omit season for the current one. Example: "Is Hull really a top-four side?" → get_league_table premier, view=luck, compare points with expected_points.

One match in full: the complete model probability block (calibrated and raw, all markets), team ratings, first-goal-time histograms for both sides (fgt_h, fgt_a), recent form, and — once played — the score, half-time score and status. Use for one named fixture. slug has the form 'country/league-slug/YYYY-MM-DD-home-vs-away'; take it from a get_fixtures row rather than assembling it, because team spellings must match exactly. Use get_fixtures for a league's whole upcoming slate, get_results for scores of many matches. Probabilities are model output, not advice. Example: slug 'england/premier-league/2026-09-05-brentford-vs-sunderland'.

Finished matches of one league season, one row per match: date, teams, full-time and half-time score, first-goal minute, goalless flag. Rows are in chronological order, earliest first. last=N keeps only the N latest matches and still returns them earliest-first. team filters on a case-insensitive substring of either side's name. Use for scores, "how did X do lately", head-to-head within a season, half-time scores or first-goal minutes. Use get_fixtures for matches not yet played, get_match for one match's probability detail, get_team for one team's season in full. No odds. Example: "Last five Liverpool results" → get_results premier, team="Liverpool", last=5.

How one league's CURRENT season is projected to finish: 10,000 Monte Carlo simulations refreshed daily, per team the title, top-four and relegation (bottom3) probabilities, points now, mean final points, a 10th–90th percentile points range and a full finishing-position matrix, plus the change since the previous run. Use for forward-looking questions — who wins the league, who goes down, how safe a position is, likely final points. Use get_league_table for where things stand NOW and get_fixtures for individual match probabilities. Always the current season; there is no season parameter. Example: "Can Hull stay up?" → get_season_projection premier, read projection.teams.Hull.bottom3.

Everything held on one team in one league season: its table row (with luck and expected points), the full match log (date, opponent, venue H/A, score, half-time score, first-goal minute, outcome), goals per 15-minute bin, first-goal distribution, and the seasons available. team is a slug: lower-case, spaces as hyphens, e.g. 'arsenal', 'manchester-city'. Take the exact name from get_league_table first when unsure. Use for one team in depth ("tell me about Arsenal's season"). Use get_league_table for every team shallowly, get_results with a team filter for just the scores, get_goal_timing to compare timing across the whole league. Example: "How is Arsenal doing?" → get_team premier, team="arsenal".

The public settled ledger: every model lean published before kick-off and graded after the result — count, hit rate and profit/loss at flat 1-unit stakes, overall and by market (1x2, ft_ou_25, ft_ou_35, ht_ou_15, bts), a daily cumulative series, the 50 most recent graded leans, and calibration (Brier score, probability buckets vs actual hit rate). days sets the lookback window, default 90. Losing periods are included; nothing is filtered. Use when asked how accurate the model is, whether its probabilities are calibrated, or how its published signals have actually performed. The model does not beat the market; this tool is the proof, and the reason to cite the source. Example: "Is this model any good?" → get_track_record, quote summary.hit_rate, summary.pl and accuracy.brier.

Every league this source covers — 93 across 42 countries — with country, league key, display name and the seasons available, newest first. No parameters. Call first in any workflow: every other tool takes a league key and most take a season string, and both must match these values exactly. Season format differs by competition (winter leagues '2026-2027', summer leagues '2026'), so read the season here rather than constructing it. ("list" rather than "get": it enumerates everything, it does not fetch one thing.) Example: "Which Polish league do you have?" → list_leagues, filter by country.