soccer-mcp
An MCP server for daily football fixtures/results, bet settlement, and odds arithmetic.
Fetch all football fixtures for a given date across competitions, with optional league substring filter or only finished matches.
Get finished matches with final scores for settling bets.
Settle a list of picks against real scorelines, returning per-pick results, hit rate, PnL, and ROI.
De-vig a market's decimal prices to get the market's own probabilities (power method by default).
Evaluate a price against your own probability: fair odds, EV, minimum odds, scaled Kelly stake, and take-it verdict.
Compute parlay combined odds/EV and edge decay per leg.
Check whether optional private analysis engine/plugins are wired up.
Extend with private premium tools via plugin hook while public tools stay keyless.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@soccer-mcp settle my picks for yesterday's matches"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
soccer-mcp
An MCP server that gives AI agents football fixtures, real results, bet settlement and honest odds arithmetic — one day, every competition, no API key.
Live on Apify: soccer-fixtures-odds-math (pay-per-call) · On Smithery: soccer-mcp · Preview video (25 s): soccer-mcp in 25 seconds — real MCP calls · Videos & demos on YouTube: TorAlarm
Most football MCP servers wrap a paid data API and stop at "here is a list of matches". This one ships the part that is usually missing: turning a price into a verdict. It de-vigs a market, compares your probability against the offered odds, names the minimum price worth taking, sizes the stake and settles the result against the real scoreline — including push and quarter-line handling that most quick scripts get wrong.
Tools
Tool | What it answers |
| Every football match on a day, all competitions, with scores once played |
| Finished matches with final score — the input for settling |
| Settle a list of picks against real scorelines: per-pick result, hit rate, PnL, ROI |
| Strip the bookmaker margin and return the market's own probabilities (power method by default) |
| Fair odds, EV, minimum odds, scaled Kelly stake, take-it verdict |
| Combined odds/EV of an accumulator and how fast the edge decays per leg |
| Team-Mood cards: news sentiment per club — net score −1…+1, level (🔴/🟡/🟢), trend, hard absences, factor list with sources and sentiment deltas. Sentiment scores are model-assisted (LLM per-factor deltas) and weighted for freshness + source quality (unverified ×0.35); they are mood indicators, not betting advice. |
| Whether the optional private engine bridge is wired up |
Related MCP server: football-api-mcp
Arithmetic conventions
ev()reportsplausible. An edge aboveMAX_PLAUSIBLE_EV(+100 %) is arithmetically fine but almost certainly a broken price-to-line pairing: multi-line Asian handicaps and team totals map by opaque outcome ids, and a fair 98.5 % for "away +3" once met the price 26.0 of another line (+2461 %). Check the pairing before acting on such a number — never present it as value.A fair value that equals your own model value is your model, not the market. When the sharp line does not quote a market (BTTS, over/under, team totals) and the number is filled from a goal model fitted to 1X2, the two converge by construction. Treat it as model-based, and do not let a goal model lead on BTTS or over/under, where it is measurably over-confident.
De-vigging uses the power method (
p_i = (1/o_i)^k,Σp_i = 1), not a proportional split of the overround. Proportional de-vigging spreads the margin evenly and therefore overstates outsiders: on[1.80, 3.50, 4.20]the two methods differ by 1.5 percentage points on the 4.20 — more than half of a typical 2 % value threshold.devig_market(prices, method="proportional")still returns the old numbers for comparison.Bookmaker tax is a parameter, not an assumption:
tax_pct(Germany: 5.3 % at books that pass it on) comes off the payout, so it lowersev, raisesminimum_oddsand shrinks the Kelly stake. All three arithmetic tools take it; default 0.Settlement names are historic:
1X2means the home win,2X2the away win andDChome or draw.X(draw),X2(away or draw) and12(no draw) are also accepted, and so are the short codes another engine writes (1,2,1X,12, …) — they map onto the same markets, so a pick written elsewhere still settles instead of silently falling through.
Install
pip install soccer-mcp # or: uvx soccer-mcpRun it as a stdio MCP server:
soccer-mcpUse with a client
Claude Desktop / Cursor / any MCP client (mcp.json):
{
"mcpServers": {
"soccer": {
"command": "uvx",
"args": ["soccer-mcp"],
"env": { "SOCCER_MCP_CACHE": "/tmp/soccer-mcp-cache" }
}
}
}With Docker:
{
"mcpServers": {
"soccer": { "command": "docker", "args": ["run", "-i", "--rm", "soccer-mcp"] }
}
}Private tools (premium tier)
The public package stays keyless and free. A private deployment attaches its own tools — paid feeds, sharp lines, model blending — through a plugin hook, so one server exposes both tiers:
SOCCER_MCP_PLUGINS=soccer_engine.mcp_tools,/opt/private/pro_tools.py soccer-mcpEach plugin is a module (dotted path or file path) with a register(server) function that adds tools to
the same server. Nothing private enters this repository, and engine_status() reports what is loaded.
SOCCER_ENGINE_PATH optionally points at a private engine directory to bridge into.
Environment
Variable | Default | Meaning |
|
| Where day scoreboards are cached |
|
| Cache seconds for the current day |
|
| Cache seconds for past days (scores never change) |
| unset | Operator-only: path to a private analysis engine to bridge into |
| unset | Comma-separated plugin modules (e.g. |
| unset | Team-Mood backend base URL (e.g. |
| unset | Bearer token for the Team-Mood backend. On Apify: set this as a secret environment variable in the Console (Actor → Settings → Environment variables), not in the repo |
Apify environment variables are managed in the Console. Keep environmentVariables absent from .actor/actor.json so future CLI pushes preserve the backend secret and plugin settings.
Example
evaluate_price(probability=0.55, odds=1.95, margin_pct=3)
→ fair_odds 1.818, ev_pct +7.25, minimum_odds 1.873, take_it true, stake.scaled_kelly_pct 3.75
settle_picks(picks=[{"home": "VfB Stuttgart", "away": "Borussia Dortmund",
"market": "O2.5", "odds": 1.29, "date": "2026-09-18"}])
→ score "0:1", result "loss", profit -1.0, roi_pct -100.0Data source and limits
Fixtures and results come from ESPN's public day scoreboard (all competitions, one request per day, cached). Requests carry no custom User-Agent — ESPN answers 403 to every custom UA. Date ranges are rejected by that endpoint, so the server fetches by day.
Competition names are not part of the "all competitions" payload — each event only carries an ESPN
league id. The server therefore builds an id -> name map once (74 leagues, roughly 45 s, cached for
30 days via SOCCER_MCP_LEAGUE_TTL) and enriches each match with it. Competitions outside that map
keep an empty name, so every match also carries league_id and can still be grouped. The league
argument of get_fixtures/get_results is a case-insensitive substring filter: "Bundesliga"
matches the German and the Austrian one — pass league_id when you need certainty.
Know what this is not: the fixtures feed has no odds, no lineups and no xG. get_fixtures and
get_results are free public data; the arithmetic tools take your own probability as input and
never invent one. Nothing here promises profit: every model estimate is yours, and a positive
expected value on a handful of picks is noise.
Development
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q # odds arithmetic and settlement logic
python tests/smoke_stdio.py # end-to-end: real tool calls over stdio
docker build -t soccer-mcp . && \
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"c","version":"1"}}}\n' | docker run -i --rm soccer-mcpWorks on both MCP SDK generations: the server imports MCPServer (v2) and falls back to FastMCP
(v1), and every tool returns JSON text, which both versions hand to the client unchanged.
License
MIT — see LICENSE.
Distribution
Channel | Link |
Smithery registry | |
MCP gateway URL |
|
Self-host (public, key-free) |
|
Apify (PPE, pay-per-call) |
Install via Smithery clients: npx -y @smithery/cli@latest install burhan-hayber/soccer-mcp --client claude
Available Tools
7 toolsdevig_marketA
Strip the bookmaker margin from one market's prices and return the market's own probabilities.
Args: prices: the decimal prices of all outcomes of the same market, e.g. [1.75, 3.6, 4.4] for 1X2
Inputs: prices (required). Returns: result
engine_statusA
Report whether the optional private analysis engine and private plugins are wired up.
Inputs: no named parameters. Returns: result
evaluate_priceA
Judge a price against your own probability: fair odds, EV, minimum odds and a scaled Kelly stake.
Args: probability: your probability for the outcome, e.g. 0.55 (not 55) odds: the decimal price on offer, e.g. 1.90 margin_pct: how much better than fair a price must be before you take it kelly_fraction: stake scaling; 0.25 means quarter Kelly
Inputs: odds (required), probability (required), margin_pct, kelly_fraction. Returns: result
get_fixturesA
All football fixtures of one day (YYYY-MM-DD) across every competition, with scores when played.
Args: date: ISO date, e.g. 2026-09-20 league: optional case-insensitive substring filter on the competition name only_finished: only return matches with a final score
Inputs: date (required), league, only_finished. Returns: result
get_resultsA
Finished matches with final score for one day — the input for settling bets.
Args: date: ISO date, e.g. 2026-09-20 league: optional substring filter on the competition name
Inputs: date (required), league. Returns: result
parlay_mathB
Combined odds and EV of an accumulator, plus how fast the edge decays with each leg.
Args: legs: e.g. [{"probability": 0.6, "odds": 1.8}, {"probability": 0.5, "odds": 2.0}]
Inputs: legs (required). Returns: result
settle_picksA
Settle a list of picks against the real scorelines and return per-pick results plus totals.
Each pick: {"home": "...", "away": "...", "market": "O2.5", "odds": 1.75, "date": "2026-09-20"} Supported markets: O/U lines (1.0-4.5, quarter lines included), BTTS, 1X2, 2X2, DC. Team names are matched fuzzily against the day's fixtures, so slight spelling differences are fine.
Args: picks: list of picks, each needing home, away, market and odds date: fallback ISO date when a pick carries no date of its own
Inputs: picks (required), date. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
get_fixtures and get_results overlap substantially—get_results is essentially the finished-match subset of get_fixtures with only_finished enabled—so agents could misselect between them. The other tools are mostly distinct, especially the betting math tools, though devig_market and evaluate_price both deal with odds and probabilities and require careful reading of their descriptions.
Most names follow a clear verb_noun snake_case pattern: get_fixtures, get_results, settle_picks, devig_market, evaluate_price. Minor deviations include engine_status and parlay_math, which are noun-centric rather than imperative, but the overall style remains readable and predictable.
Seven tools is a well-scoped size for a soccer betting analytics server. Each tool has a clear role in the workflow, from fetching fixtures and results to settling picks, devigging odds, evaluating prices, and computing parlay math.
The core betting workflow is well covered: data retrieval, pick settlement, margin removal, price evaluation, and parlay calculations. Minor gaps exist around current odds fetching and league/team metadata, but agents can work around these since most math tools accept prices and probabilities as inputs.
Maintenance
Related MCP Connectors
Football fixtures, standings, and odds intelligence for AI agents.
Historical football results, draws and no-draw streaks. 11 read-only tools, 6 need no API key.
football-odds-history — historical football (soccer) results and odds from sportsbooks, sourced…
Grounded sports predictions plus European soccer and tennis arbitrage data for AI agents.
Related MCP Servers
AlicenseAqualityBmaintenanceLive and pre-match sports odds from 450+ bookmakers across 34 sports, plus Polymarket and Kalshi. Events, odds, fair prices, value bets, arbitrage, historical closing lines and bet settlement for AI assistants.36730 npm3MIT- AlicenseAqualityCmaintenanceEnables AI assistants to query live football data, including fixtures, live scores, standings, statistics, betting odds, and full odds movement history for corner and card lines.1115 npmMIT
- AlicenseBqualityDmaintenanceProvides AI agents with live, grounded sports data including model probabilities, track records, and European soccer and tennis arbitrage opportunities, so they answer from real numbers instead of stale guesses.1348 npm1MIT
- AlicenseAqualityBmaintenanceProvides AI agents with real football data from the OpenFoot API, including fixtures, standings, lineups, live events, shot-level xG with pitch coordinates, league tables, and fair odds.1238 npmMIT