footballcharts-mcp
Tables, results, fixtures, goal timing, season projections: 93 football leagues incl. lower tiers
Should I use this
Quality & Safety
A
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
~5,618Tokens (tool definitions)
~4.8 KBTypical response size
Significant attention impact (4.39% of 128k context)
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"footballcharts-mcp": {
"command": "npx",
"args": [
"footballcharts-mcp"
]
}
}
}Runnable packages
npmfootballcharts-mcp
0.5.0stdioRemote endpoints
https://mcp.football-charts.com/mcpstreamable-httpWhat it can do
Tool inventory
Tools (10)
🟢 Read-only🟡 Write🔴 Delete⚪ Unknown
🟢about_football_charts
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.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"what": {
"type": "string"
},
"covers": {
"type": "array",
"items": {
"type": "string"
}
},
"not_held": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
},
"free_tier": {
"type": "string"
},
"get_a_key": {
"type": "string"
},
"tools": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"what",
"covers",
"not_held",
"notes",
"free_tier",
"get_a_key",
"tools"
],
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢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.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"leagues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "The key to pass as `league`"
},
"name": {
"type": "string"
},
"country": {
"type": "string"
},
"seasons": {
"type": "array",
"items": {
"type": "string"
},
"description": "Newest first; exact strings for `season`"
},
"url": {}
},
"required": [
"league",
"name",
"country",
"seasons"
],
"additionalProperties": true
}
},
"count": {},
"season_window": {},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"required": [
"leagues"
],
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_league_table(league, season, view)
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.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
},
"season": {
"type": "string",
"description": "Season string as listed by list_leagues: '2026-2027' for winter-calendar leagues, '2026' for summer-calendar leagues (Brazil, Sweden, Norway, Japan…). Omit for the current season. The free tier serves the current and previous season."
},
"view": {
"anyOf": [
{
"type": "string",
"enum": [
"classic",
"luck",
"goals"
]
},
{
"type": "null"
}
],
"description": "Row order; default 'classic' (by points)"
}
},
"required": [
"league"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"league": {},
"season": {},
"season_state": {
"description": "'in_season' or 'finished'"
},
"current_season": {},
"view": {},
"table": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"team": {
"type": "string"
},
"position": {},
"played": {},
"won": {},
"drawn": {},
"lost": {},
"goals_for": {},
"goals_against": {},
"goal_difference": {},
"points": {},
"last_5_form": {
"description": "Latest results as letters, e.g. 'WWDLW'"
},
"last_5_points": {},
"expected_points": {
"description": "Points the underlying numbers say the team should have"
},
"luck_difference": {
"description": "points − expected_points; positive = ahead of the numbers"
},
"luck_category": {
"description": "'lucky' | 'fair' | 'unlucky'"
},
"expected_position": {},
"avg_goals_scored": {},
"avg_goals_conceded": {},
"clean_sheets": {},
"over_25_percentage": {}
},
"required": [
"team"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_results(league, season, team, last)
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.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
},
"season": {
"type": "string",
"description": "Season string as listed by list_leagues: '2026-2027' for winter-calendar leagues, '2026' for summer-calendar leagues (Brazil, Sweden, Norway, Japan…). Omit for the current season. The free tier serves the current and previous season."
},
"team": {
"type": [
"string",
"null"
],
"description": "Team name substring, e.g. 'Liverpool'"
},
"last": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 500
},
{
"type": "null"
}
],
"description": "Keep only the N latest matches of the season, e.g. 5 for recent form (default: all)"
}
},
"required": [
"league"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"league": {},
"season": {},
"season_state": {
"description": "'in_season' or 'finished'"
},
"current_season": {},
"count": {},
"note": {},
"matches": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {},
"time": {},
"homeTeam": {
"type": "string"
},
"awayTeam": {
"type": "string"
},
"score": {
"description": "Full-time 'home:away', e.g. '3:0'"
},
"ht_result": {
"description": "Half-time 'home:away'"
},
"first_goal_time": {
"description": "Minute of the first goal; null when goalless"
},
"first_goal_time_extra": {
"description": "Stoppage-time minutes added to first_goal_time"
},
"goalless": {
"type": [
"boolean",
"null"
]
}
},
"required": [
"homeTeam",
"awayTeam"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_fixtures(league)
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.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
}
},
"required": [
"league"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"league": {},
"count": {},
"matches": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Input to get_match"
},
"home_team": {
"type": "string"
},
"away_team": {
"type": "string"
},
"match_date": {},
"time": {},
"status": {},
"league": {},
"country": {},
"real_league_name": {},
"model_predictions": {
"anyOf": [
{
"type": "object",
"properties": {
"dc_v2": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {},
"calibrated": {
"anyOf": [
{
"type": "object",
"properties": {
"home": {},
"away": {},
"btts_yes": {},
"over_0.5": {},
"over_1.5": {},
"over_2.5": {},
"over_3.5": {},
"over_4.5": {},
"ht_over_0.5": {},
"ht_over_1.5": {},
"expected_home_goals": {},
"expected_away_goals": {},
"expected_ht_goals": {}
},
"additionalProperties": true,
"description": "Probabilities 0–1. The draw is NOT a field: draw = 1 − home − away."
},
{
"type": "null"
}
],
"description": "Use these. Calibrated on settled matches."
},
"data_through": {
"description": "Last match date the model has seen"
},
"computed_at": {}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"required": [
"slug",
"home_team",
"away_team"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_match(slug)
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.
Input Schema
{
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Match slug as listed in upcoming fixtures, e.g. 'england/premier-league/2026-09-05-brentford-vs-sunderland'"
}
},
"required": [
"slug"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"match": {
"type": "object",
"properties": {
"slug": {},
"label": {},
"league": {},
"real_league_name": {},
"country": {},
"season": {},
"match_date": {},
"time": {},
"home_team": {},
"away_team": {},
"match_status": {
"description": "'scheduled' before kick-off; 'ft' when finished"
},
"home_score": {},
"away_score": {},
"ht_result": {},
"model_predictions": {
"anyOf": [
{
"type": "object",
"properties": {
"dc_v2": {
"anyOf": [
{
"type": "object",
"properties": {
"model": {},
"calibrated": {
"anyOf": [
{
"type": "object",
"properties": {
"home": {},
"away": {},
"btts_yes": {},
"over_0.5": {},
"over_1.5": {},
"over_2.5": {},
"over_3.5": {},
"over_4.5": {},
"ht_over_0.5": {},
"ht_over_1.5": {},
"expected_home_goals": {},
"expected_away_goals": {},
"expected_ht_goals": {}
},
"additionalProperties": true,
"description": "Probabilities 0–1. The draw is NOT a field: draw = 1 − home − away."
},
{
"type": "null"
}
],
"description": "Use these. Calibrated on settled matches."
},
"data_through": {
"description": "Last match date the model has seen"
},
"computed_at": {}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"fgt_h": {
"anyOf": [
{
"type": "array"
},
{
"type": "null"
}
],
"description": "Home side first-goal-time histogram"
},
"fgt_a": {
"anyOf": [
{
"type": "array"
},
{
"type": "null"
}
],
"description": "Away side first-goal-time histogram"
}
},
"additionalProperties": true
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"required": [
"match"
],
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_season_projection(league)
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.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
}
},
"required": [
"league"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"projection": {
"anyOf": [
{
"type": "object",
"properties": {
"league": {},
"season": {},
"run_date": {},
"n_sims": {},
"scheduled_remaining": {},
"expected_remaining": {},
"partial_schedule": {
"type": [
"boolean",
"null"
]
},
"teams": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {},
"top4": {},
"bottom3": {
"description": "Relegation-zone probability (bottom three)"
},
"bottom1": {},
"bottom2": {},
"pts_now": {},
"played": {},
"gd_now": {},
"mean_pts": {},
"p10_pts": {},
"p90_pts": {},
"position_matrix": {
"anyOf": [
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "null"
}
],
"description": "Probability of finishing 1st…last"
}
},
"additionalProperties": true
},
"description": "Keyed by team name"
},
"deltas_vs_prev": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"title": {},
"top4": {},
"bottom3": {}
},
"additionalProperties": true
}
},
{
"type": "null"
}
],
"description": "Change since the previous run"
}
},
"required": [
"teams"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"note": {
"description": "Set when no projection exists for the league yet"
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_team(league, team, season)
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'.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
},
"team": {
"type": "string",
"description": "Team slug, e.g. 'arsenal', 'manchester-city' (from the table's team names, lower-case, spaces as hyphens)"
},
"season": {
"type": "string",
"description": "Season string as listed by list_leagues: '2026-2027' for winter-calendar leagues, '2026' for summer-calendar leagues (Brazil, Sweden, Norway, Japan…). Omit for the current season. The free tier serves the current and previous season."
}
},
"required": [
"league",
"team"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"team": {},
"slug": {},
"league": {},
"season": {},
"seasons": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"ranking": {
"anyOf": [
{
"type": "object",
"properties": {
"team": {
"type": "string"
},
"position": {},
"played": {},
"won": {},
"drawn": {},
"lost": {},
"goals_for": {},
"goals_against": {},
"goal_difference": {},
"points": {},
"last_5_form": {
"description": "Latest results as letters, e.g. 'WWDLW'"
},
"last_5_points": {},
"expected_points": {
"description": "Points the underlying numbers say the team should have"
},
"luck_difference": {
"description": "points − expected_points; positive = ahead of the numbers"
},
"luck_category": {
"description": "'lucky' | 'fair' | 'unlucky'"
},
"expected_position": {},
"avg_goals_scored": {},
"avg_goals_conceded": {},
"clean_sheets": {},
"over_25_percentage": {}
},
"required": [
"team"
],
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "The team's table row"
},
"matches": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {},
"time": {},
"home": {},
"away": {},
"venue": {
"description": "'H' or 'A'"
},
"score": {},
"ht": {},
"first_goal_time": {},
"outcome": {
"description": "'W' | 'D' | 'L'"
}
},
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"first_goal_bins": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"time": {},
"count": {}
},
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"matches_with_stats": {},
"shots_avg": {},
"shots_on_target_avg": {},
"shots_against_avg": {},
"possession_avg": {},
"corners_avg": {},
"xg_avg": {},
"xg_against_avg": {}
},
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Per-match averages over this season, computed from stored match statistics; null where the league has none"
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_goal_timing(league, season, team)
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.
Input Schema
{
"type": "object",
"properties": {
"league": {
"type": "string",
"description": "League key as listed by list_leagues, e.g. 'premier' (England), 'spain1', 'brazil1', 'sweden1', 'wgermany1' (women). Not the display name."
},
"season": {
"type": "string",
"description": "Season string as listed by list_leagues: '2026-2027' for winter-calendar leagues, '2026' for summer-calendar leagues (Brazil, Sweden, Norway, Japan…). Omit for the current season. The free tier serves the current and previous season."
},
"team": {
"type": [
"string",
"null"
],
"description": "Team name substring, e.g. 'Flamengo' — returns that team's row only"
}
},
"required": [
"league"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"league": {},
"season": {},
"time_bins": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"total_goals": {},
"most_active_period": {},
"late_goals": {},
"match_count": {}
},
"additionalProperties": true
},
{
"type": "null"
}
]
},
"data": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"team": {
"type": "string"
},
"total": {},
"bins": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "number"
}
},
{
"type": "null"
}
],
"description": "Goals per bin: '0-15','15-30','30-45','45+','46-60','60-75','75-90','90+'"
},
"peak_bins": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Bin(s) with most goals — ties are listed; report a tie as a tie"
},
"peak_goals": {},
"late_share_pct": {
"description": "% of goals from 75′ on"
},
"first_half_pct": {}
},
"required": [
"team"
],
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"team_filter": {},
"team_not_found": {},
"note": {},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_track_record(days)
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).
Input Schema
{
"type": "object",
"properties": {
"days": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 365
},
{
"type": "null"
}
],
"description": "Lookback window in days (default 90)"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Output Schema
{
"type": "object",
"properties": {
"track_record": {
"type": "object",
"properties": {
"summary": {
"anyOf": [
{
"type": "object",
"properties": {
"n": {
"description": "Scored predictions"
},
"correct": {},
"incorrect": {},
"void": {
"description": "Postponed or abandoned; not scored"
},
"hit_rate": {
"description": "correct / (correct + incorrect)"
}
},
"additionalProperties": true
},
{
"type": "null"
}
],
"description": "Whole window"
},
"by_question": {
"anyOf": [
{
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"n": {
"description": "Scored predictions"
},
"correct": {},
"incorrect": {},
"void": {
"description": "Postponed or abandoned; not scored"
},
"hit_rate": {
"description": "correct / (correct + incorrect)"
}
},
"additionalProperties": true
}
},
{
"type": "null"
}
]
},
"recent": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"slug": {},
"home_team": {},
"away_team": {},
"league": {},
"match_date": {},
"question": {},
"side": {},
"line": {},
"model_prob": {},
"outcome": {
"description": "'correct' | 'incorrect' | 'void'"
},
"result_score": {}
},
"additionalProperties": true
}
},
{
"type": "null"
}
],
"description": "The 50 most recent scored predictions"
},
"pending": {
"description": "Published but not yet scored"
},
"accuracy": {
"anyOf": [
{
"type": "object",
"properties": {
"n": {},
"brier": {
"description": "Brier score over scored probabilities; lower is better, 0.25 = coin flip"
},
"buckets": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"lo": {},
"hi": {},
"n": {},
"avg_prob": {},
"hit_rate": {}
},
"additionalProperties": true
}
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Cite as \"Data by football-charts.com\""
}
},
"required": [
"track_record"
],
"additionalProperties": true,
"$schema": "http://json-schema.org/draft-07/schema#"
}Community
Evidence
Recent observations
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools
verifiedversion not recorded10 tools