io.github.Ninjabeam20/sportiq-mcp

sportiq-mcp

MCP server that turns any AI assistant into a sports analyst across FIFA World Cup 2026 football, Formula 1, and IPL cricket — 46 AI-callable tools.

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)

Plus sportiq_health (included in the 46; cache backend + per-adapter status and remaining API quota).

MCP resources (static JSON, readable without a tool call): sportiq://instructions, sportiq://football/wc2026/draw, sportiq://football/team-codes, sportiq://f1/circuits, sportiq://cricket/venues, sportiq://cricket/teams, sportiq://cricket/scoring-profile.

Data sources (per chain, with keyless fallbacks): football → API-Football → football-data.org → openfootball (keyless) → bundled wc2026.json; standings fall back to a table derived from fixture results. F1 → OpenF1 → Jolpica → fastf1. Cricket → CricAPI → RapidAPI Cricbuzz (paid fallback) + static seeds (NDTV/Cricbuzz scrapers opt-in). Odds (football + cricket) → The Odds API.

Where it works

Anywhere that speaks MCP — Claude (Desktop + web), ChatGPT, Cursor, and any MCP client. Two ways to run it:

• Hosted (no install): add a custom connector — works in claude.ai web & ChatGPT.
• Local (uvx/Desktop config/IDEs): install from PyPI.

How it works

Hosted — no install

A public instance runs on the home server behind Cloudflare. Add this as a custom connector with No authentication:

https://sportiq.utkarshgupta.org/mcp

Hosting history (GCP Cloud Run → home server): docs/wiki/findings/product-hosting-arc.md. Old *.run.app connector URLs are gone.

• claude.ai (web): Settings → Connectors → Add custom connector → paste URL → Save.
• ChatGPT: Settings → Apps & Connectors → enable Developer mode → Create app (MCP) → paste URL → No authentication → Connect.

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.

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

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

Claude Desktop config:

{
  "mcpServers": {
    "sportiq": {
      "command": "uvx",
      "args": ["sportiq-mcp"],
      "env": {
        "CRICAPI_KEY": "your_cricapi_key",
        "APIFOOTBALL_KEY": "your_apifootball_key",
        "THEODDS_KEY": "your_theodds_key"
      }
    }
  }
}

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.

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.

If SportIQ saves you time, sponsor the project at github.com/sponsors/Ninjabeam20 to help fund hosting and ongoing development. It's a voluntary donation — you get the same fully-unlocked server either way.

Is it safe?

• 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

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:

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.
• Cricsheet — ball-by-ball IPL data → derived venue scoring priors (venues.json).
• martj42 international football results (CC0) — Elo backtesting.
• OpenF1 — F1 timing data (runtime source). Historical sessions are keyless; live-session telemetry needs paid auth, which SportIQ does not wire.
• football-data.org — free football data (runtime source).

License & author

Created and maintained by Utkarsh Gupta (@Ninjabeam20). Licensed under the MIT License — © 2026 Utkarsh Gupta. Canonical package: sportiq-mcp on PyPI / io.github.Ninjabeam20/sportiq-mcp in the official MCP registry.