MCP tools for FIFA World Cup 2026 football, Formula 1, and IPL cricket — sims, strategy, fantasy.
This MCP server provides tools for sports-related content, specifically FIFA World Cup 2026 football, Formula 1, and IPL cricket. Its description characterizes the scope as simulations, strategy, and fantasy, and the repository lists 44 available tools.
🛠️ Key Features
MCP tools covering FIFA World Cup 2026 football
MCP tools covering Formula 1
MCP tools covering IPL cricket
Tools span sims, strategy, and fantasy
44 total tools
🚀 Use Cases
Integrate World Cup 2026 football–related functionality via MCP tools
Support Formula 1 workflows using provided MCP tools
Use IPL cricket tools for simulation, strategy, or fantasy-related tasks
⚡ Developer Benefits
Python package available for installation (PyPI)
MIT-licensed repository
CI workflow indicated by repository badges
⚠️ Limitations
Limited to the sports domains explicitly listed: FIFA World Cup 2026, Formula 1, and IPL cricket
Captured live from the server via tools/list.
sportiq_health
Report cache backend, per-adapter healthcheck, and quota status.
Returns:
HealthReport-shaped dict with `cache_backend`, `cache_ok`,
`adapters` (per-source ok/detail), and `quotas`.
Return the FIFA World Cup 2026 group draw and advancement format.
Returns:
data.groups: {group_letter: [4 team codes]} for all 12 groups.
data.format: 48-team / 12-group / top-2 + 8-best-thirds rule.
data.teams: team-code -> {name, fifa_code} metadata.
meta.source: adapter that served the data.
Return World Cup 2026 fixtures (live providers, else the group schedule).
Args:
limit: Max fixtures to return, 1..200 (default 50).
offset: Number of fixtures to skip for paging (default 0).
Returns:
data.fixtures: page of {home, away, date/group, status, home_goals, away_goals}.
data.pagination: {total, count, offset, limit, has_more, next_offset}.
meta.source: adapter that served the data (static_seed = group schedule only).
Parameters2
limit
integer
optional
Max fixtures to return, 1..200 (default 50).
offset
integer
optional
Number of fixtures to skip for paging (default 0).
Return current World Cup 2026 group standings.
Args:
limit: Max standing rows to return, 1..200 (default 50).
offset: Number of rows to skip for paging (default 0).
Returns:
data.standings: page of {rank, team, group, points, played, goals_diff}.
data.pagination: {total, count, offset, limit, has_more, next_offset}.
meta.source: adapter that served the data.
Return a national team's World Cup squad.
Args:
team: Team code or name (e.g. "ARG"). Live rosters need an API-Football
key; without one the static seed serves an empty-but-valid squad
(no rosters are bundled).
Returns:
data.squad: list of {name, number, position, age} (empty from the seed).
meta.source: adapter that served the data.
meta.note: present when the seed served it — how to get live squads.
Parameters1
team
string
required
Team code or name (e.g. "ARG"). Live rosters need an API-Football key; without one the static seed serves an empty-but-valid squad (no rosters are bundled).
Raw schema
{
"type": "object",
"properties": {
"team": {
"title": "Team",
"type": "string",
"description": "Team code or name (e.g. \"ARG\"). Live rosters need an API-Football key; without one the static seed serves an empty-but-valid squad (no rosters are bundled)."
}
},
"required": [
"team"
],
"title": "football_get_squadArguments"
}
football_get_match_stats
Return a team's aggregate World Cup tournament statistics.
Network-only enrichment: requires a configured API-Football (or
football-data.org) key. There is no offline static fallback, so without a
key the call returns a clean ALL_SOURCES_FAILED envelope.
Args:
team: API-Football numeric team id (not a country code).
Returns:
data.team_stats: {team, played, wins, goals_for, goals_against}.
meta.source: adapter that served the data.
Parameters1
team
integer
required
API-Football numeric team id (not a country code).
Raw schema
{
"type": "object",
"properties": {
"team": {
"title": "Team",
"type": "integer",
"description": "API-Football numeric team id (not a country code)."
}
},
"required": [
"team"
],
"title": "football_get_match_statsArguments"
}
football_get_top_scorers
Return the World Cup 2026 top scorers.
Returns:
data.scorers: list of {name, team, goals, assists}.
meta.source: adapter that served the data.
Return market head-to-head odds for any World Cup 2026 events the odds feed still lists.
Sourced from The Odds API (requires THEODDS_KEY). Without a key the call
returns a clean ALL_SOURCES_FAILED envelope rather than crashing. The
tournament ended with the 2026-07-19 final, so the feed is normally empty.
Args:
team: Optional team name to filter events (case-insensitive substring,
matched against both sides). Omit to return every WC event.
Returns:
data.events: list of {event_id, home, away, commence_time, bookmakers:
[{name, home, draw, away, last_update}]} with decimal 1X2 prices per bookmaker.
meta.source: adapter that served the data (theodds / cache:stale).
Parameters1
team
any
optional
Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every WC event.
Raw schema
{
"type": "object",
"properties": {
"team": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Team",
"description": "Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every WC event."
}
},
"title": "football_get_oddsArguments"
}
football_xg_model
Estimate a match's expected goals and win/draw/loss probabilities.
Args:
home_team: First team, FIFA code or name (e.g. "ARG" or "Argentina").
away_team: Second team, FIFA code or name (e.g. "BRA" or "Brazil").
neutral: True for a neutral venue (no home advantage). World Cup default.
Returns:
data: {expected_home_goals, expected_away_goals, home_win, draw, away_win}.
meta.estimated: true.
Parameters3
home_team
string
required
First team, FIFA code or name (e.g. "ARG" or "Argentina").
away_team
string
required
Second team, FIFA code or name (e.g. "BRA" or "Brazil").
neutral
boolean
optional
True for a neutral venue (no home advantage). World Cup default.
Raw schema
{
"type": "object",
"properties": {
"home_team": {
"title": "Home Team",
"type": "string",
"description": "First team, FIFA code or name (e.g. \"ARG\" or \"Argentina\")."
},
"away_team": {
"title": "Away Team",
"type": "string",
"description": "Second team, FIFA code or name (e.g. \"BRA\" or \"Brazil\")."
},
"neutral": {
"default": true,
"title": "Neutral",
"type": "boolean",
"description": "True for a neutral venue (no home advantage). World Cup default."
}
},
"required": [
"home_team",
"away_team"
],
"title": "football_xg_modelArguments"
}
football_match_predictor
Predict a single match: most likely scoreline + outcome probabilities.
Args:
home_team: First team, FIFA code or name (e.g. "ESP" or "Spain").
away_team: Second team, FIFA code or name.
neutral: True for a neutral venue (World Cup default).
Returns:
data: {most_likely_score, home_win, draw, away_win, predicted_winner}.
meta.estimated: true.
Parameters3
home_team
string
required
First team, FIFA code or name (e.g. "ESP" or "Spain").
away_team
string
required
Second team, FIFA code or name.
neutral
boolean
optional
True for a neutral venue (World Cup default).
Raw schema
{
"type": "object",
"properties": {
"home_team": {
"title": "Home Team",
"type": "string",
"description": "First team, FIFA code or name (e.g. \"ESP\" or \"Spain\")."
},
"away_team": {
"title": "Away Team",
"type": "string",
"description": "Second team, FIFA code or name."
},
"neutral": {
"default": true,
"title": "Neutral",
"type": "boolean",
"description": "True for a neutral venue (World Cup default)."
}
},
"required": [
"home_team",
"away_team"
],
"title": "football_match_predictorArguments"
}
football_simulate_group
Monte Carlo one group within the full 12-group qualification context.
Args:
group: Group letter A-L (also accepts "Group A").
iterations: Number of simulations (clamped to 100..20000).
Returns:
data.teams: Per-team position probabilities, p_auto_advance,
p_best_third_advance, truthful combined p_advance, and avg_points.
data.iterations: iterations actually run.
meta.estimated: true. meta.conditioned_matches: completed matches locked in.
Monte Carlo the full World Cup 2026 — per-team round + title probabilities.
Simulates all 12 groups, advances the top 2 + 8 best third-placed teams to a
32-team knockout, and plays it to a champion, ``iterations`` times.
Args:
iterations: Number of tournament simulations (clamped to 100..20000;
~10000 gives stable ±2% probabilities).
seed: Optional RNG seed for reproducible output.
Returns:
data.teams: {code: {reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}}
sorted by win probability descending.
data.champion: most likely winner.
data.iterations: iterations run.
meta.estimated: true. meta.conditioned_matches: completed matches locked in
(played group results fixed, decided knockout ties locked).
Example:
football_simulate_bracket()
football_simulate_bracket(iterations=20000, seed=42)
Parameters2
iterations
integer
optional
Number of tournament simulations (clamped to 100..20000; ~10000 gives stable ±2% probabilities).
Round-by-round survival probabilities for one team in the full sim.
Args:
team: FIFA code or name (e.g. "FRA" or "France").
iterations: Number of tournament simulations (clamped to 100..20000).
seed: Optional RNG seed.
Returns:
data: {team, reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}.
meta.estimated: true.
Parameters3
team
string
required
FIFA code or name (e.g. "FRA" or "France").
iterations
integer
optional
Number of tournament simulations (clamped to 100..20000).
Replay World Cup 2026 from a chosen stage, optionally flipping one real knockout result.
Keeps every real result played before ``replay_from`` and Monte-Carlos the
rest of the tournament from there. ``flip_winner_of`` makes one decided
knockout tie in the kept results go the other way first.
Args:
replay_from: Stage to re-simulate from: "group" (whole tournament, no
real results kept), "r32", "r16", "qf", "sf" or "final" (keeps every
result before the final and simulates only the final).
flip_winner_of: Optional tie to flip, as two FIFA codes or names joined
by a hyphen in any order (e.g. "ESP-FRA"). It must be a decided
knockout tie before ``replay_from``.
iterations: Number of tournament simulations (clamped to 100..20000).
seed: Optional RNG seed for reproducible output.
Returns:
data.teams: {code: {reach_r32, reach_r16, reach_qf, reach_sf, reach_final, win}}
sorted by win probability descending.
data.champion: most likely winner. data.iterations: iterations run.
meta.mode: "what_if". meta.replay_from: the stage. meta.flipped:
{tie: [code_a, code_b], winner: code} or null. meta.estimated: true.
Example:
football_what_if(replay_from="qf")
football_what_if(replay_from="final", flip_winner_of="ESP-FRA", seed=7)
Parameters4
replay_from
string
optional
Stage to re-simulate from: "group" (whole tournament, no real results kept), "r32", "r16", "qf", "sf" or "final" (keeps every result before the final and simulates only the final).
flip_winner_of
any
optional
Optional tie to flip, as two FIFA codes or names joined by a hyphen in any order (e.g. "ESP-FRA"). It must be a decided knockout tie before ``replay_from``.
iterations
integer
optional
Number of tournament simulations (clamped to 100..20000).
seed
any
optional
Optional RNG seed for reproducible output.
Raw schema
{
"type": "object",
"properties": {
"replay_from": {
"default": "group",
"enum": [
"group",
"r32",
"r16",
"qf",
"sf",
"final"
],
"title": "Replay From",
"type": "string",
"description": "Stage to re-simulate from: \"group\" (whole tournament, no real results kept), \"r32\", \"r16\", \"qf\", \"sf\" or \"final\" (keeps every result before the final and simulates only the final)."
},
"flip_winner_of": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Flip Winner Of",
"description": "Optional tie to flip, as two FIFA codes or names joined by a hyphen in any order (e.g. \"ESP-FRA\"). It must be a decided knockout tie before ``replay_from``."
},
"iterations": {
"default": 10000,
"title": "Iterations",
"type": "integer",
"description": "Number of tournament simulations (clamped to 100..20000)."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Seed",
"description": "Optional RNG seed for reproducible output."
}
},
"title": "football_what_ifArguments"
}
football_find_value_bets
Surface the largest gaps between the model's win probability and the market.
De-vigs each market's 1X2 decimal odds (removes the margin so implied
probabilities sum to 1) and compares them to this server's own match-outcome
probabilities — the same Elo/Poisson path ``football_match_predictor`` uses.
Flags outcomes where the model beats the de-vigged market by ``min_edge``
**and** the offered price has positive expected value, with the edge, the
expected value and the model's fair odds. Events that have already started
are skipped.
Args:
team: Optional FIFA code or team name to filter events (matched against
both sides; an unrecognised value falls back to a case-insensitive
substring match). Omit to scan every WC 2026 odds event.
min_edge: Minimum edge (model_prob - devigged_market_prob), 0..1.
Default 0.05 (5 percentage points).
Returns:
data.value_bets: list of {event_id, home, away, outcome, model_prob,
fair_odds, market_odds, edge, ev_pct, bookmaker, price_updated_at},
sorted by edge descending.
data.events_analysed: not-yet-started events with both teams in the draw.
meta.estimated: true. meta.is_stale reflects the odds freshness.
Parameters2
team
any
optional
Optional FIFA code or team name to filter events (matched against both sides; an unrecognised value falls back to a case-insensitive substring match). Omit to scan every WC 2026 odds event.
{
"type": "object",
"properties": {
"team": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Team",
"description": "Optional FIFA code or team name to filter events (matched against both sides; an unrecognised value falls back to a case-insensitive substring match). Omit to scan every WC 2026 odds event."
},
"min_edge": {
"default": 0.05,
"title": "Min Edge",
"type": "number",
"description": "Minimum edge (model_prob - devigged_market_prob), 0..1. Default 0.05 (5 percentage points)."
}
},
"title": "football_find_value_betsArguments"
}
football_form_trends
Return rolling form, goal record, and xG trend for a football team.
Args:
team: FIFA code (e.g. ARG) or name (e.g. "Argentina", "South Korea").
Returns:
data: {form_string, wins, draws, losses, goals_scored, goals_conceded,
xg_for, xg_against, recent_trend, matches_analysed}.
meta.estimated: true — derived from available fixture data.
Parameters1
team
string
required
FIFA code (e.g. ARG) or name (e.g. "Argentina", "South Korea").
Model the joint probability of several match outcomes from the top model-vs-market gaps.
Calls ``football_find_value_bets`` internally to fetch live odds, then selects
the strongest legs and combines them under the joint-probability model.
Args:
legs: Number of legs (2-8). Default 3.
min_edge: Minimum edge threshold per leg. Default 0.05.
Returns:
data: {legs, legs_used, combined_odds, combined_model_prob, combined_edge,
risk_flag, independence_warning}.
meta.estimated: true.
Return F1 sessions for a given year, optionally filtered by country or session name.
Args:
year: Championship year (e.g. 2026).
country: Optional country name to filter (e.g. "Netherlands").
session_name: Optional session name to keep, case-insensitive (e.g. "Race",
"Qualifying", "Sprint").
latest_completed: When true, return only the single session that ended most
recently (greatest date_end before now, UTC) — e.g. with
session_name="Race", the latest finished Grand Prix.
Returns:
data.sessions: list of session objects with session_key, session_type, date.
meta.source: adapter that served the data.
Parameters4
year
integer
required
Championship year (e.g. 2026).
country
any
optional
Optional country name to filter (e.g. "Netherlands").
session_name
any
optional
Optional session name to keep, case-insensitive (e.g. "Race", "Qualifying", "Sprint").
latest_completed
boolean
optional
When true, return only the single session that ended most recently (greatest date_end before now, UTC) — e.g. with session_name="Race", the latest finished Grand Prix.
Raw schema
{
"type": "object",
"properties": {
"year": {
"title": "Year",
"type": "integer",
"description": "Championship year (e.g. 2026)."
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Country",
"description": "Optional country name to filter (e.g. \"Netherlands\")."
},
"session_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Session Name",
"description": "Optional session name to keep, case-insensitive (e.g. \"Race\", \"Qualifying\", \"Sprint\")."
},
"latest_completed": {
"default": false,
"title": "Latest Completed",
"type": "boolean",
"description": "When true, return only the single session that ended most recently (greatest date_end before now, UTC) — e.g. with session_name=\"Race\", the latest finished Grand Prix."
}
},
"required": [
"year"
],
"title": "f1_get_sessionsArguments"
}
f1_get_drivers
Return driver list for a specific F1 session.
Args:
session_key: OpenF1 session identifier.
Returns:
data.drivers: list of driver objects with driver_number, full_name, team.
meta.source: adapter that served the data.
Return lap times for a driver in a specific F1 session.
Args:
session_key: OpenF1 session identifier.
driver_number: Driver's race number (driver numbers change by season; use f1_get_drivers).
limit: Max laps to return, 1..200 (default 100 — covers most full races).
offset: Number of laps to skip for paging (default 0).
Returns:
data.laps: page of lap objects with lap_number and lap_duration. OpenF1
does not put compound/tyre_life here — those live on the stints endpoint.
data.pagination: {total, count, offset, limit, has_more, next_offset}.
meta.source: adapter that served the data.
Parameters4
session_key
integer
required
OpenF1 session identifier.
driver_number
integer
required
Driver's race number (driver numbers change by season; use f1_get_drivers).
limit
integer
optional
Max laps to return, 1..200 (default 100 — covers most full races).
offset
integer
optional
Number of laps to skip for paging (default 0).
Raw schema
{
"type": "object",
"properties": {
"session_key": {
"title": "Session Key",
"type": "integer",
"description": "OpenF1 session identifier."
},
"driver_number": {
"title": "Driver Number",
"type": "integer",
"description": "Driver's race number (driver numbers change by season; use f1_get_drivers)."
},
"limit": {
"default": 100,
"title": "Limit",
"type": "integer",
"description": "Max laps to return, 1..200 (default 100 — covers most full races)."
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer",
"description": "Number of laps to skip for paging (default 0)."
}
},
"required": [
"session_key",
"driver_number"
],
"title": "f1_get_lap_timesArguments"
}
f1_get_standings
Return F1 driver and constructor championship standings for a year.
Use this for "who is leading / who will win the F1 championship this year".
For title probabilities use f1_simulate_championship.
This is not a cricket or football tool.
Args:
year: Championship year (e.g. 2026).
Returns:
data.season / data.round: season and the last round counted.
data.drivers: [{position, driver_number, code, name, team, points, wins}]
(points are season totals).
data.constructors: [{position, team, points, wins}].
Same shape from every source (Jolpica primary; the FastF1 fallback
sums per-race points and omits sprint points).
meta.source: adapter that served the data.
Return the final classification for one F1 race, keyed by year and round.
Args:
year: Championship year (e.g. 2025).
round: Round number within the season (1-based; e.g. 1 for the opener).
Returns:
data.results: Ergast/Jolpica RaceTable payload — finishing order, times,
grid positions, points, and fastest laps for the race.
meta.source: adapter that served the data.
Parameters2
year
integer
required
Championship year (e.g. 2025).
round
integer
required
Round number within the season (1-based; e.g. 1 for the opener).
Raw schema
{
"type": "object",
"properties": {
"year": {
"title": "Year",
"type": "integer",
"description": "Championship year (e.g. 2025)."
},
"round": {
"title": "Round",
"type": "integer",
"description": "Round number within the season (1-based; e.g. 1 for the opener)."
}
},
"required": [
"year",
"round"
],
"title": "f1_get_race_resultsArguments"
}
f1_get_weather
Return weather data for a specific F1 session.
Args:
session_key: OpenF1 session identifier.
Returns:
data.weather: list of weather snapshots with temperature, rainfall, wind.
meta.source: adapter that served the data.
Fit a tyre degradation model for a driver + compound in a session.
Args:
session_key: OpenF1 session identifier.
driver_number: Driver's race number.
compound: Tyre compound (SOFT, MEDIUM, HARD, INTER, WET; "INTERMEDIATE" = INTER).
Returns:
data: {intercept, slope, residual_std, sample_count}.
meta.estimated: true — model output, not telemetry oracle.
Parameters3
session_key
integer
required
OpenF1 session identifier.
driver_number
integer
required
Driver's race number.
compound
string
required
Tyre compound (SOFT, MEDIUM, HARD, INTER, WET; "INTERMEDIATE" = INTER).
Estimate whether an undercut is viable for the attacker against the target.
Args:
session_key: OpenF1 session identifier.
attacker_number: Attacking driver's race number.
target_number: Target driver's race number.
current_lap: Current lap number in the race.
Returns:
data: {laps_to_clear, viable, marginal}.
meta.gap_to_target_s: attacker-minus-target race time at current_lap.
meta.gap_source: "cumulative_lap_time", or "default" (assumed 2.0 s, also
in meta.assumed_gap_s) when either driver lacks a full lap history.
meta.estimated: true.
Compare lap-time pace distribution between two drivers in a session.
Args:
session_key: OpenF1 session identifier.
driver_a: First driver's race number.
driver_b: Second driver's race number.
Returns:
data: {driver_a_avg_s, driver_b_avg_s, delta_s, faster_driver}. The
"avg" values are median lap times after dropping pit-out laps and
slow outliers (safety-car / in-laps).
meta.estimated: true.
Predict the optimal pit-stop strategy for a driver in an F1 race session.
Args:
session_key: OpenF1 session identifier for a recorded race.
driver_number: Driver's race number (driver numbers change by season; use f1_get_drivers).
current_lap: Current lap to project from (default 1 = full race ahead).
total_laps: Total race laps. If omitted, estimated from the regulation
minimum race distance (305 km; Monaco 260 km) over the circuit's lap
length; INVALID_INPUT when the circuit is unknown. An explicit value
always wins.
Returns:
data.stop_laps: recommended pit laps.
data.compound_sequence: tyre compounds for each stint.
data.expected_finish_position: currently always None (not modelled).
data.confidence: 0.0-1.0 model confidence.
data.net_saving_s: stay-out time minus the best one-stop time (seconds).
data.current_tyre_age: laps on the current tyre set at current_lap.
meta.total_laps: race length used.
meta.total_laps_source: "explicit" or "regulation_estimate".
meta.estimated: true.
Example:
f1_predict_pit_strategy(session_key=11353, driver_number=1, total_laps=72)
f1_predict_pit_strategy(session_key=11353, driver_number=1, current_lap=20)
Parameters4
session_key
integer
required
OpenF1 session identifier for a recorded race.
driver_number
integer
required
Driver's race number (driver numbers change by season; use f1_get_drivers).
current_lap
integer
optional
Current lap to project from (default 1 = full race ahead).
total_laps
any
optional
Total race laps. If omitted, estimated from the regulation minimum race distance (305 km; Monaco 260 km) over the circuit's lap length; INVALID_INPUT when the circuit is unknown. An explicit value always wins.
Raw schema
{
"type": "object",
"properties": {
"session_key": {
"title": "Session Key",
"type": "integer",
"description": "OpenF1 session identifier for a recorded race."
},
"driver_number": {
"title": "Driver Number",
"type": "integer",
"description": "Driver's race number (driver numbers change by season; use f1_get_drivers)."
},
"current_lap": {
"default": 1,
"title": "Current Lap",
"type": "integer",
"description": "Current lap to project from (default 1 = full race ahead)."
},
"total_laps": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Total Laps",
"description": "Total race laps. If omitted, estimated from the regulation minimum race distance (305 km; Monaco 260 km) over the circuit's lap length; INVALID_INPUT when the circuit is unknown. An explicit value always wins."
}
},
"required": [
"session_key",
"driver_number"
],
"title": "f1_predict_pit_strategyArguments"
}
f1_simulate_championship
Estimate each driver's F1 drivers' title probability for the rest of a season.
Monte Carlo over the remaining races and sprints (Plackett-Luce finishing
orders weighted by each driver's season points rate), plus exact
elimination maths: a driver who cannot catch the leader's current points
even by winning every remaining race and sprint has title_prob 0.0.
This is not a cricket or football tool.
Args:
year: Championship season (2018-2030, default 2026).
iterations: Monte Carlo iterations, clamped to 1000-20000 (default 10000).
seed: Optional RNG seed for reproducible probabilities.
Returns:
data.drivers: [{code, points_now, title_prob, expected_points,
eliminated, max_possible}] sorted by title_prob.
data.max_remaining_points: most points one driver can still score.
data.rounds_remaining: races left after the last completed round.
meta.estimated: true. meta.model: "plackett-luce-points-rate".
meta.is_stale: true if standings or schedule came from stale cache.
Parameters3
year
integer
optional
Championship season (2018-2030, default 2026).
iterations
integer
optional
Monte Carlo iterations, clamped to 1000-20000 (default 10000).
Analyse a qualifying session: best lap per driver, gap to pole, projected grid.
Args:
session_key: OpenF1 session identifier for a Qualifying session.
Returns:
data.grid: [{position, driver_number, full_name, team_name, best_lap_gap_s}].
data.pole_time_s: pole lap duration in seconds.
data.drivers_analysed: count of drivers with valid laps.
meta.estimated: true — grid derived from session laps, not official timing.
Parameters1
session_key
integer
required
OpenF1 session identifier for a Qualifying session.
Raw schema
{
"type": "object",
"properties": {
"session_key": {
"title": "Session Key",
"type": "integer",
"description": "OpenF1 session identifier for a Qualifying session."
}
},
"required": [
"session_key"
],
"title": "f1_qualifying_analysisArguments"
}
f1_race_pace_compare
Compare race-pace and tyre degradation between two F1 drivers in a session.
Args:
session_key: OpenF1 session identifier.
driver_a: First driver's race number.
driver_b: Second driver's race number.
Returns:
data: {by_compound, overall_faster, compounds_compared}.
meta.estimated: true — degradation model fit, not official timing.
Return all currently live cricket matches across all series.
Returns:
data.matches: list of live match objects (team names, score, status).
meta.source: which adapter served the response.
meta.is_stale: true if data is from stale cache.
Return the full scorecard for a specific match.
Args:
match_id: The match identifier (e.g. from cricket_get_live_matches).
Returns:
data: full scorecard with innings, partnerships, bowling figures.
meta.source: adapter that served the data.
Parameters1
match_id
string
required
The match identifier (e.g. from cricket_get_live_matches).
Raw schema
{
"type": "object",
"properties": {
"match_id": {
"title": "Match Id",
"type": "string",
"description": "The match identifier (e.g. from cricket_get_live_matches)."
}
},
"required": [
"match_id"
],
"title": "cricket_get_scorecardArguments"
}
cricket_get_points_table
Return the points table / standings for a cricket series.
Args:
series_id: The series identifier (e.g. IPL 2026 series ID from CricAPI).
Returns:
data: points table rows with team, P, W, L, NRR, Points.
meta.source: adapter that served the data.
Parameters1
series_id
string
required
The series identifier (e.g. IPL 2026 series ID from CricAPI).
Raw schema
{
"type": "object",
"properties": {
"series_id": {
"title": "Series Id",
"type": "string",
"description": "The series identifier (e.g. IPL 2026 series ID from CricAPI)."
}
},
"required": [
"series_id"
],
"title": "cricket_get_points_tableArguments"
}
cricket_get_schedule
Return the upcoming match schedule, optionally filtered by series.
Args:
series_id: Optional. Filter to a specific series. If omitted, returns
all upcoming fixtures across all active series.
limit: Max matches to return, 1..200 (default 50).
offset: Number of matches to skip for paging (default 0).
Returns:
data.matches: page of matches dated today (UTC) or later, with teams,
date, venue; filtered to ``series_id`` when the source labels series.
data.pagination: {total, count, offset, limit, has_more, next_offset}.
meta.source: adapter that served the data.
Parameters3
series_id
any
optional
Optional. Filter to a specific series. If omitted, returns all upcoming fixtures across all active series.
limit
integer
optional
Max matches to return, 1..200 (default 50).
offset
integer
optional
Number of matches to skip for paging (default 0).
Raw schema
{
"type": "object",
"properties": {
"series_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Series Id",
"description": "Optional. Filter to a specific series. If omitted, returns all upcoming fixtures across all active series."
},
"limit": {
"default": 50,
"title": "Limit",
"type": "integer",
"description": "Max matches to return, 1..200 (default 50)."
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer",
"description": "Number of matches to skip for paging (default 0)."
}
},
"title": "cricket_get_scheduleArguments"
}
cricket_get_squad
Return the squad roster for a cricket team, optionally for a specific series.
Args:
team: Team code or name (e.g. "MI", "CSK", "IND", "AUS").
series_id: Optional. Series ID to pull the tournament-specific squad.
If omitted, falls back to static seed data.
Returns:
data.players: list of players with name, role, and credits.
meta.source: adapter that served the data (cricapi / static_seed).
Parameters2
team
string
required
Team code or name (e.g. "MI", "CSK", "IND", "AUS").
series_id
any
optional
Optional. Series ID to pull the tournament-specific squad. If omitted, falls back to static seed data.
Raw schema
{
"type": "object",
"properties": {
"team": {
"title": "Team",
"type": "string",
"description": "Team code or name (e.g. \"MI\", \"CSK\", \"IND\", \"AUS\")."
},
"series_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Series Id",
"description": "Optional. Series ID to pull the tournament-specific squad. If omitted, falls back to static seed data."
}
},
"required": [
"team"
],
"title": "cricket_get_squadArguments"
}
cricket_get_live_odds
Return live market head-to-head odds for upcoming/live IPL matches.
IPL only (~March-May). An empty ``events`` list outside that window is a
successful empty market, not an outage. Not international/Test/other T20
leagues. For World Cup 2026 football odds use ``football_get_odds``.
Sourced from The Odds API (requires THEODDS_KEY). Without a key the call
returns a clean ALL_SOURCES_FAILED envelope rather than crashing.
Args:
team: Optional team name to filter events (case-insensitive substring,
matched against both sides). Omit to return every IPL event. The
Odds API uses its own opaque event ids, so a CricAPI match_id
cannot be resolved to an event yet — filtering is by team name.
Returns:
data.events: list of {event_id, home, away, commence_time, bookmakers:
[{name, home, away}]} with decimal h2h prices per bookmaker.
Empty when no IPL events are listed (typical off-season).
meta.source: adapter that served the data (theodds / cache:stale).
Parameters1
team
any
optional
Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every IPL event. The Odds API uses its own opaque event ids, so a CricAPI match_id cannot be resolved to an event yet — filtering is by team name.
Raw schema
{
"type": "object",
"properties": {
"team": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Team",
"description": "Optional team name to filter events (case-insensitive substring, matched against both sides). Omit to return every IPL event. The Odds API uses its own opaque event ids, so a CricAPI match_id cannot be resolved to an event yet — filtering is by team name."
}
},
"title": "cricket_get_live_oddsArguments"
}
cricket_build_dream11_team
Recommend an optimal fantasy XI + captain + vice-captain for one fixture.
Args:
match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a: First team code/name (e.g. ``MI``). Required if match_id is absent.
team_b: Second team code/name (e.g. ``CSK``). Required if match_id is absent.
venue: Venue key/name (e.g. ``wankhede``). Required if match_id is absent.
strategy: ``"balanced"`` only in Phase 2; future variants reserved.
Returns:
data.players: 11 picked players with name/role/credits/team/projected_points.
data.captain: name of the chosen captain.
data.vice_captain: name of the chosen VC.
data.total_credits: sum of credits used (<= 100).
data.total_projected_points: fantasy points including C x2 and VC x1.5 boosts.
meta.estimated: true — projections are model output, not a fantasy oracle.
meta.form_source: "default_neutral" (role-based projections; see meta.note).
meta.scoring_profile: the Dream11 T20 points profile id.
meta.excluded_missing_credits: players dropped for having no contest credits.
Example:
cricket_build_dream11_team(team_a="MI", team_b="CSK", venue="wankhede")
cricket_build_dream11_team(match_id="abc123")
Parameters5
match_id
any
optional
CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a
any
optional
First team code/name (e.g. ``MI``). Required if match_id is absent.
team_b
any
optional
Second team code/name (e.g. ``CSK``). Required if match_id is absent.
venue
any
optional
Venue key/name (e.g. ``wankhede``). Required if match_id is absent.
strategy
string
optional
``"balanced"`` only in Phase 2; future variants reserved.
Return the top-3 captain candidates ranked by projected points.
IPL venues only (pitch seed is IPL grounds). Test/international matches
and unknown venues fail rather than inventing a ranking. Same-role
players often tie: projections use default form 55 and default
opposition 0.5, not per-player history.
Args:
match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a: First team code/name. Required if match_id is absent.
team_b: Second team code/name. Required if match_id is absent.
venue: Venue key/name (IPL ground, e.g. ``wankhede``). Required if match_id is absent.
Returns:
data.candidates: list of 3 dicts with name/role/team/projected_points.
meta.source: model:captain_score.
meta.estimated: true. meta.form_source: "default_neutral".
Parameters4
match_id
any
optional
CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a
any
optional
First team code/name. Required if match_id is absent.
team_b
any
optional
Second team code/name. Required if match_id is absent.
venue
any
optional
Venue key/name (IPL ground, e.g. ``wankhede``). Required if match_id is absent.
Suggest low-ownership picks with positive projected upside.
Ownership is *estimated* — proxied by credit weight (lower-credit players
tend to have lower ownership), not real ownership data. Flagged
``estimated: true`` in the response.
Args:
match_id: CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a: First team code/name. Required if match_id is absent.
team_b: Second team code/name. Required if match_id is absent.
venue: Venue key/name. Required if match_id is absent.
ownership_threshold: percent ownership cap; affects estimated label.
Returns:
data.picks: list of {name, role, team, credits, projected_points,
estimated_ownership_pct, ownership_pct_estimated}.
meta.source: model:captain_score (filtered).
meta.estimated: true. meta.ownership_source: "heuristic_from_credits".
meta.form_source: "default_neutral".
Parameters5
match_id
any
optional
CricAPI match identifier; resolves team_a/team_b/venue automatically.
team_a
any
optional
First team code/name. Required if match_id is absent.
team_b
any
optional
Second team code/name. Required if match_id is absent.
Report a 0-100 form score for a player using the player_stats chain.
Args:
player_id: Upstream player identifier (CricAPI/Cricbuzz id).
Returns:
data.form_score: 0..100 indicator.
data.trend: "rising" / "stable" / "falling".
data.samples: how many recent innings were available.
meta.source: which adapter served the underlying stats.
meta.estimated: true.
Summarise pitch characteristics for a venue.
Args:
venue: Venue key (e.g. ``wankhede``), official name, or city.
Returns:
data: {batting_friendly 0..1, expected_first_inn, recommendation,
venue, pitch_type}.
meta.source: which adapter served the venue record.
Parameters1
venue
string
required
Venue key (e.g. ``wankhede``), official name, or city.
Compare model probabilities against market-implied IPL odds. Requires THEODDS_KEY.
NOTE: cricket has no calibrated team-strength model wired yet (unlike the
football Elo/Poisson path), so this tool currently returns an EMPTY
``value_bets`` list — scoring an edge against a neutral 50/50 prior would flag
every market underdog, which would be misleading. It
still reports how many events were screened so callers know odds were
available. For raw de-vigged prices use ``cricket_get_live_odds``. Real edge
detection lands when a cricket win model is wired (see cricket_head_to_head);
it will flag outcomes where the model beats the de-vigged market by
``min_edge`` **and** the offered price has positive expected value.
Args:
team: Optional team name to filter events (case-insensitive substring).
Omit to scan every IPL odds event.
min_edge: Minimum edge (model_prob - devigged_market_prob), 0..1.
Default 0.05. Currently informational only (no bets emitted).
Returns:
data.value_bets: always ``[]`` until a cricket model is wired.
data.events_analysed: count of not-yet-started events screened (both teams present).
data.model: ``"neutral_baseline"``. data.note: why no bets are emitted.
meta.estimated: true.
Parameters2
team
any
optional
Optional team name to filter events (case-insensitive substring). Omit to scan every IPL odds event.
min_edge
number
optional
Minimum edge (model_prob - devigged_market_prob), 0..1. Default 0.05. Currently informational only (no bets emitted).
Raw schema
{
"type": "object",
"properties": {
"team": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Team",
"description": "Optional team name to filter events (case-insensitive substring). Omit to scan every IPL odds event."
},
"min_edge": {
"default": 0.05,
"title": "Min Edge",
"type": "number",
"description": "Minimum edge (model_prob - devigged_market_prob), 0..1. Default 0.05. Currently informational only (no bets emitted)."
}
},
"title": "cricket_find_value_betsArguments"
}
cricket_head_to_head
Compare two cricket teams head-to-head using squad form and player stats.
Args:
team_a: First team code or name (e.g. "MI", "India").
team_b: Second team code or name (e.g. "CSK", "Australia").
Returns:
data: {team_a, team_b, team_a_edge_count, team_b_edge_count,
key_players_a, key_players_b, h2h_win_rate_a, h2h_win_rate_b,
win_prob_a, win_prob_b}.
meta.estimated: true.
meta.estimate_quality: "uninformative" when no player stats were available
(both sides at default form), else "player_stats".
Parameters2
team_a
string
required
First team code or name (e.g. "MI", "India").
team_b
string
required
Second team code or name (e.g. "CSK", "Australia").
Raw schema
{
"type": "object",
"properties": {
"team_a": {
"title": "Team A",
"type": "string",
"description": "First team code or name (e.g. \"MI\", \"India\")."
},
"team_b": {
"title": "Team B",
"type": "string",
"description": "Second team code or name (e.g. \"CSK\", \"Australia\")."
}
},
"required": [
"team_a",
"team_b"
],
"title": "cricket_head_to_headArguments"
}
cricket_player_matchup
Analyse the head-to-head matchup between two cricket players based on role and career stats.
Args:
player_a: CricAPI player ID for the first player (names are not resolved).
player_b: CricAPI player ID for the second player (names are not resolved).
Returns:
data: {matchup_type, edge_holder, edge_reason, signals, role_a, role_b}.
meta.estimated: true — heuristic model, not ball-by-ball H2H data.
Parameters2
player_a
string
required
CricAPI player ID for the first player (names are not resolved).
player_b
string
required
CricAPI player ID for the second player (names are not resolved).
Raw schema
{
"type": "object",
"properties": {
"player_a": {
"title": "Player A",
"type": "string",
"description": "CricAPI player ID for the first player (names are not resolved)."
},
"player_b": {
"title": "Player B",
"type": "string",
"description": "CricAPI player ID for the second player (names are not resolved)."
}
},
"required": [
"player_a",
"player_b"
],
"title": "cricket_player_matchupArguments"
}
cross_sport_build_accumulator
Model the joint probability of multiple outcomes across football and cricket.
Args:
legs: Total legs across both sports (2-8). Default 3.
min_edge: Minimum edge per leg. Default 0.05.
Returns:
data: same shape as football_build_accumulator, with sport field per leg.
meta.estimated: true.
SportIQ demo — Claude calling football_simulate_bracket for World Cup 2026 title probabilities
SportIQ running live in Claude — Monte Carlo World Cup bracket, F1 pit strategy, and Dream11 optimisation, each a visible MCP tool call. (1-min demo)
Every tool is free to use — the three flagships and everything in the INTEL columns below have no SportIQ paywall or account requirement. Live/provider-backed data still depends on the keys and quota available to the host or local operator. If SportIQ is useful to you, sponsor the project to support ongoing development.
What's new in v0.4.0
Two new tools (46 total):
f1_simulate_championship: a title-race Monte Carlo with exact elimination maths.
football_what_if: replays World Cup 2026 from any stage, optionally flipping one real knockout result.
Completed-tournament mode: World Cup tools now answer from the real 2026 results (Spain won the final 1–0 after extra time) instead of re-simulating.
7 MCP resources: static reference data (the WC draw, team codes, F1 circuits, IPL venues and teams, the Dream11 scoring profile) plus the instructions.
Accuracy fixes:
Official Dream11 T20 scoring and IPL squads generated from Cricsheet.
An F1 pit model that sums the whole remaining race, legal compound sequences and the regulation race distance.
Positive-EV value bets only.
Extra-time and penalty results kept, team-name and venue resolution, and many more.
Reliability:
A fix for a cache bug that wiped the cache about once a minute.
No more per-request teardown errors.
A /healthz liveness route.
A 30 s per-tool deadline (TOOL_DEADLINE_SECONDS) and a 15 s budget per data chain.
API keys no longer appear in logs.
Upgrade:uvx sportiq-mcp@latest picks up 0.4.0. The hosted connector URL stays the same.
What it does
Raw-data tools are table stakes; the intelligence layer is the product. Three flagships:
football_simulate_bracket — Monte Carlo with Poisson xG over the 48-team WC 2026 format → per-team round + title probabilities.
f1_predict_pit_strategy — tyre-degradation model on OpenF1 telemetry → optimal stop laps + compound sequence.
cricket_build_dream11_team — PuLP constraint solver → a valid fantasy XI under credit/role/team caps.
Tools (46 total)
Sport
RAW data
INTEL
Football (WC 2026)
groups, fixtures, standings, squad, match stats, top scorers, odds
All 46 tools register on the plain URL. Whether a live/provider-backed call can return current data depends on the credentials, quota, and fallbacks available to the hosted operator; the repository does not claim the public instance's current key inventory.
Mode
What is available
Hosted
All tools register; live/provider-backed results depend on the host's current keys, quota, and fallbacks.
Local, keyless
All tools register; bundled seeds and keyless sources work where supported, while credential-only live sources are skipped.
Local, BYO keys
The same tools can use the configured providers for fresher/live data, subject to provider quota.
The hosted HTTP boundary rejects request bodies over 1 MiB, limits traffic to 60 requests per client and 300 total requests per minute, and permits at most two concurrent expensive model/solver calls. These counters are per process, so the home-server Compose stack runs one replica (always-on idle; no scale-to-zero).
Local install
bash
uvx sportiq-mcp # from PyPI# or from source:
git clone https://github.com/Ninjabeam20/SportIQ-MCP && cd SportIQ-MCP
uv sync --extra dev && uv run python -m sportiq.server # --extra dev = pytest/ruff for contributors
The server boots and registers every tool without keys. Seed/keyless fallbacks and the intelligence layer work where their required inputs are available; provider keys add fresher/live sources and quota rather than unlocking a separate paid tool tier.
Var
Unlocks
Free tier
APIFOOTBALL_KEY
Live football fixtures / standings / squads / scorers
100 req/day
THEODDS_KEY
Market odds (football + cricket probability tools)
500 req/month
FOOTBALLDATA_KEY
football-data.org fallback — required for World Cup endpoints (they return 403 without it)
10 req/min, 100/day
CRICAPI_KEY
Live cricket scores / scorecards / schedules / squads
100 req/day
RAPIDAPI_KEY
Paid Cricbuzz fallback (player career stats)
plan-dependent
SPORTIQ_ENABLE_NDTV / SPORTIQ_ENABLE_CRICBUZZ
Opt-in cricket scrapers (off by default — ToS)
—
REDIS_URL
Shared cache backend (defaults to local diskcache)
—
SPORTIQ_TRANSPORT
stdio (default, local) or http (remote / home server)
—
TOOL_DEADLINE_SECONDS
Per-tool deadline (default 30); a slower call returns UPSTREAM_TIMEOUT
—
macOS arm64: the Dream11 solver needs CBC — brew install cbc (the binary bundled with PuLP is x86-only).
Self-host
Set SPORTIQ_TRANSPORT=http and the server serves the MCP endpoint at /mcp (binds 0.0.0.0:$PORT). GET /healthz returns 200 ok for liveness only (it never touches the cache, chains or network). A ready-to-build Dockerfile and home-server docker-compose.yml are included. cloud.md is the old Cloud Run runbook (historical). With your own keys set, the live-score and odds tools come online too.
Support SportIQ
Every tool is free and open source — the raw-data tools, sportiq_health, and the full intelligence layer (the three flagships + everything in the INTEL columns). SportIQ has no paid feature gate; provider-backed data can still require operator credentials and quota.
Open source, MIT licensed, published on PyPI with signed build attestations — read the code before you connect it.
Read-only. Tools only fetch and analyse public sports data — no write, delete, payment, email, or file-system tools.
Limited operational telemetry. HTTP mode logs client software name/version, User-Agent, tool name, outcome, latency, selected source, and staleness. The public host (Dell) can persist tool_call / mcp_request lines to a local JSONL volume. Local stdio emits local logs but sends no telemetry to a SportIQ-hosted service.
Hosted abuse controls. HTTP POST bodies are capped at 1 MiB; requests are limited to 60/client/minute and 300/process/minute; the seven expensive simulation/strategy/solver tools share a concurrency limit of two; every tool call has a 30 s deadline (TOOL_DEADLINE_SECONDS) and each fallback chain a 15 s total budget.
Credential-aware. A hosted operator may configure provider credentials; the repository does not claim the public instance's current key inventory. Keys are redacted from application logs and envelopes.
Historical automated AI code-review results are documented in SECURITY.md; they are not a current third-party certification.
Every response carries a meta.is_stale flag + data age, so the AI tells you how fresh each answer is. Cricket live scores refresh ~30s, F1 completed-session laps/stints ~24h, standings ~10min, football fixtures ~6h (the WC 2026 is over).
Develop
bash
uv sync --extra dev --extra analytics # always both extras: dev = pytest/ruff, analytics = the dashboard's GCP libs
uv run pytest
uv run ruff check .
npx @modelcontextprotocol/inspector uv run python -m sportiq.server
Analytics dashboard (read-only local usage view — Dell JSONL / archived GCP / PyPI / GitHub). Same setup as above, then just run it:
bash
uv run python scripts/dashboard.py # writes dashboard.html and opens it; GITHUB_TOKEN optional (Sponsors panel)
Note: the dashboard's HTML template (scripts/dashboard_template.html) is currently local-only maintainer tooling, so a fresh clone can't render it yet.
Repository layout:src/ is the MCP server (published to PyPI, hosted on the Dell at https://sportiq.utkarshgupta.org/mcp); website/ is the Next.js marketing site deployed to Vercel. The two ship independently — website/ is excluded from the Python package and the backend container.
See CLAUDE.md for collaboration rules and docs/index.md for the wiki entry point.
Data sources & credits
SportIQ derives some model constants offline from open datasets. Raw datasets are never shipped or fetched at runtime — only small derived seeds (circuits.json, venues.json, elo_seed.json) are committed.
F1DB (CC BY 4.0) — per-circuit stop counts + lap lengths; pit loss measured offline from OpenF1 laps.