Skip to main content
Glama
soccer-mcp

soccer-mcp

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

get_fixtures(date, league?, only_finished?)

Every football match on a day, all competitions, with scores once played

get_results(date, league?)

Finished matches with final score — the input for settling

settle_picks(picks, date?)

Settle a list of picks against real scorelines: per-pick result, hit rate, PnL, ROI

devig_market(prices, method?)

Strip the bookmaker margin and return the market's own probabilities (power method by default)

evaluate_price(probability, odds, margin_pct?, kelly_fraction?, tax_pct?)

Fair odds, EV, minimum odds, scaled Kelly stake, take-it verdict

parlay_math(legs)

Combined odds/EV of an accumulator and how fast the edge decays per leg

get_team_sentiment(date?, teams?)

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.

engine_status()

Whether the optional private engine bridge is wired up

Related MCP server: football-api-mcp

Arithmetic conventions

  • ev() reports plausible. An edge above MAX_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 lowers ev, raises minimum_odds and shrinks the Kelly stake. All three arithmetic tools take it; default 0.

  • Settlement names are historic: 1X2 means the home win, 2X2 the away win and DC home or draw. X (draw), X2 (away or draw) and 12 (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-mcp

Run it as a stdio MCP server:

soccer-mcp

Use 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-mcp

Each 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

SOCCER_MCP_CACHE

~/.cache/soccer-mcp

Where day scoreboards are cached

SOCCER_MCP_TTL

900

Cache seconds for the current day

SOCCER_MCP_FINISHED_TTL

604800

Cache seconds for past days (scores never change)

SOCCER_ENGINE_PATH

unset

Operator-only: path to a private analysis engine to bridge into

SOCCER_MCP_PLUGINS

unset

Comma-separated plugin modules (e.g. soccer_mcp.plugins_sentiment)

SOCCER_SENTIMENT_URL

unset

Team-Mood backend base URL (e.g. https://…/soccer) — enables get_team_sentiment

SOCCER_SENTIMENT_TOKEN

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.0

Data 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-mcp

Works 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

smithery.ai/servers/burhan-hayber/soccer-mcp

MCP gateway URL

https://mcp.smithery.ai/burhan-hayber/soccer-mcp (Bearer Smithery key)

Self-host (public, key-free)

https://vmd194739.contaboserver.net/mcp/soccer/mcp

Apify (PPE, pay-per-call)

https://apify.com/genkenobi/soccer-fixtures-odds-math

Install via Smithery clients: npx -y @smithery/cli@latest install burhan-hayber/soccer-mcp --client claude

Available Tools

7 tools
devig_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

    A3.8/5.0

    Scored across 7 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Live 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.
      36
      730 npm
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      11
      15 npm
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Provides 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.
      13
      48 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides 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.
      12
      38 npm
      MIT