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

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 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 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 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 — 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)