sportiq-mcp

MCP server that turns any AI assistant into a sports analyst across FIFA World Cup 2026 football, Formula 1, and IPL cricket — 44 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 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 (44 total)

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

Data sources (per chain, with keyless fallbacks): football → API-Football → football-data.org → bundled wc2026.json. F1 → OpenF1 → Jolpica → fastf1. Cricket → CricAPI + static seeds (NDTV/Cricbuzz scrapers opt-in).

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

Cloud Run https://sportiq-mcp-ey2eariulq-uc.a.run.app/mcp remains rollback until GCP teardown.

Confused about hosting or why Cloud Run still exists? See docs/wiki/findings/product-hosting-arc.md (GCP → paid plan → free on GCP → home server).

• 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 44 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 --extra analytics && uv run python -m sportiq.server

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). A ready-to-build Dockerfile is included; see cloud.md for a Google Cloud Run deploy (free tier). 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; Cloud Run may also retain platform network/request metadata. Local stdio emits local logs but sends no SportIQ-host telemetry.
• Hosted abuse controls. HTTP POST bodies are capped at 1 MiB; requests are limited to 60/client/minute and 300/process/minute; the five expensive simulation/strategy/solver tools share a concurrency limit of two.
• 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. Live scores refresh ~30s, F1 telemetry ~10s, standings ~10min, fixtures ~6h.

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 — Cloud Run / 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, deployed to Cloud Run); 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 — keyless live F1 telemetry (runtime source).
• 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.