{ "markdown": "# sportiq-mcp\n\n\n\n[![CI](https://github.com/Ninjabeam20/SportIQ-MCP/actions/workflows/test.yml/badge.svg)](https://github.com/Ninjabeam20/SportIQ-MCP/actions/workflows/test.yml)\n[![PyPI](https://img.shields.io/pypi/v/sportiq-mcp.svg)](https://pypi.org/project/sportiq-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/sportiq-mcp.svg)](https://pypi.org/project/sportiq-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io)\n\nMCP 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.\n\n![SportIQ demo — Claude calling football_simulate_bracket for World Cup 2026 title probabilities](docs/assets/demo.gif)\n\n*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](docs/assets/SportIQ.mp4))*\n\n

\n \"Sponsor\n  \n \"Website\"\n

\n\n> **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](https://github.com/sponsors/Ninjabeam20) to support ongoing development.\n\n## What it does\n\nRaw-data tools are table stakes; the intelligence layer is the product. Three flagships:\n\n- **`football_simulate_bracket`** — Monte Carlo with Poisson xG over the 48-team WC 2026 format → per-team round + title probabilities.\n- **`f1_predict_pit_strategy`** — tyre-degradation model on OpenF1 telemetry → optimal stop laps + compound sequence.\n- **`cricket_build_dream11_team`** — PuLP constraint solver → a valid fantasy XI under credit/role/team caps.\n\n### Tools (44 total)\n\n| Sport | RAW data | INTEL |\n|-------|----------|-------|\n| **Football** (WC 2026) | groups, fixtures, standings, squad, match stats, top scorers, odds | xg_model, match_predictor, simulate_group, **simulate_bracket**, knockout_path, form_trends, find_value_bets, build_accumulator |\n| **F1** | sessions, drivers, lap_times, standings, race_results, weather | tyre_degradation, undercut_window, head_to_head_pace, weather_strategy_impact, qualifying_analysis, race_pace_compare, **predict_pit_strategy** |\n| **Cricket** (IPL) | live_matches, scorecard, points_table, schedule, squad, live_odds | **build_dream11_team**, captain_recommendation, differential_picks, player_form_index, pitch_report, head_to_head, player_matchup, find_value_bets |\n| **Cross-sport** | — | build_accumulator |\n\nPlus `sportiq_health` (included in the 44; cache backend + per-adapter status and remaining API quota).\n\n**Data sources** (per chain, with keyless fallbacks): football → [API-Football](https://www.api-football.com) → [football-data.org](https://football-data.org) → bundled `wc2026.json`. F1 → [OpenF1](https://openf1.org) → [Jolpica](https://jolpi.ca) → `fastf1`. Cricket → CricAPI + static seeds (NDTV/Cricbuzz scrapers opt-in).\n\n## Where it works\n\nAnywhere that speaks MCP — Claude (Desktop + web), ChatGPT, Cursor, and any MCP client. Two ways to run it:\n\n- **Hosted (no install):** add a custom connector — works in claude.ai web & ChatGPT.\n- **Local (`uvx`/Desktop config/IDEs):** install from PyPI.\n\n## How it works\n\n### Hosted — no install\n\nA public instance runs on the home server behind Cloudflare. Add this as a custom connector with **No authentication**:\n\n```\nhttps://sportiq.utkarshgupta.org/mcp\n```\n\nHosting history (GCP Cloud Run → home server): [`docs/wiki/findings/product-hosting-arc.md`](docs/wiki/findings/product-hosting-arc.md). Old `*.run.app` connector URLs are gone.\n\n- **claude.ai (web):** Settings → Connectors → Add custom connector → paste URL → Save.\n- **ChatGPT:** Settings → Apps & Connectors → enable **Developer mode** → Create app (MCP) → paste URL → No authentication → Connect.\n\nAll 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.\n\n| Mode | What is available |\n|------|-------------------|\n| **Hosted** | All tools register; live/provider-backed results depend on the host's current keys, quota, and fallbacks. |\n| **Local, keyless** | All tools register; bundled seeds and keyless sources work where supported, while credential-only live sources are skipped. |\n| **Local, BYO keys** | The same tools can use the configured providers for fresher/live data, subject to provider quota. |\n\nThe 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).\n\n### Local install\n\n```bash\nuvx sportiq-mcp # from PyPI\n# or from source:\ngit clone https://github.com/Ninjabeam20/SportIQ-MCP && cd sportiq-mcp\nuv sync --extra dev --extra analytics && uv run python -m sportiq.server\n```\n\n**Claude Desktop config:**\n\n```json\n{\n \"mcpServers\": {\n \"sportiq\": {\n \"command\": \"uvx\",\n \"args\": [\"sportiq-mcp\"],\n \"env\": {\n \"CRICAPI_KEY\": \"your_cricapi_key\",\n \"APIFOOTBALL_KEY\": \"your_apifootball_key\",\n \"THEODDS_KEY\": \"your_theodds_key\"\n }\n }\n }\n}\n```\n\nThe 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.\n\n| Var | Unlocks | Free tier |\n|-----|---------|-----------|\n| `APIFOOTBALL_KEY` | Live football fixtures / standings / squads / scorers | 100 req/day |\n| `THEODDS_KEY` | Market odds (football + cricket probability tools) | 500 req/month |\n| `FOOTBALLDATA_KEY` | football-data.org fallback (token optional) | 10 req/min |\n| `CRICAPI_KEY` | Live cricket scores / scorecards / schedules / squads | 100 req/day |\n| `RAPIDAPI_KEY` | Paid Cricbuzz fallback (player career stats) | plan-dependent |\n| `SPORTIQ_ENABLE_NDTV` / `SPORTIQ_ENABLE_CRICBUZZ` | Opt-in cricket scrapers (off by default — ToS) | — |\n| `REDIS_URL` | Shared cache backend (defaults to local diskcache) | — |\n| `SPORTIQ_TRANSPORT` | `stdio` (default, local) or `http` (remote / home server) | — |\n\n> macOS arm64: the Dream11 solver needs CBC — `brew install cbc` (the binary bundled with PuLP is x86-only).\n\n### Self-host\n\nSet `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.\n\n## Support SportIQ\n\nEvery 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.\n\nIf SportIQ saves you time, **[sponsor the project at github.com/sponsors/Ninjabeam20](https://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.\n\n## Is it safe?\n\n- **Open source, MIT licensed**, published on [PyPI](https://pypi.org/project/sportiq-mcp/) with signed build attestations — read the code before you connect it.\n- **Read-only.** Tools only fetch and analyse public sports data — no write, delete, payment, email, or file-system tools.\n- **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.\n- **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.\n- **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.\n- Historical automated AI code-review results are documented in [`SECURITY.md`](SECURITY.md#independent-review); they are not a current third-party certification.\n\nEvery 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.\n\n## Develop\n\n```bash\nuv sync --extra dev --extra analytics # always both extras: dev = pytest/ruff, analytics = the dashboard's GCP libs\nuv run pytest\nuv run ruff check .\nnpx @modelcontextprotocol/inspector uv run python -m sportiq.server\n```\n\n**Analytics dashboard** (read-only local usage view — Dell JSONL / archived GCP / PyPI / GitHub). Same setup as above, then just run it:\n\n```bash\nuv run python scripts/dashboard.py # writes dashboard.html and opens it; GITHUB_TOKEN optional (Sponsors panel)\n```\n\n> 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.\n\n**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.\n\nSee `CLAUDE.md` for collaboration rules and `docs/index.md` for the wiki entry point.\n\n## Data sources & credits\n\nSportIQ 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.\n\n- **[F1DB](https://github.com/f1db/f1db)** (CC BY 4.0) — per-circuit stop counts + lap lengths; pit **loss** measured offline from OpenF1 laps.\n- **[Cricsheet](https://cricsheet.org)** — ball-by-ball IPL data → derived venue scoring priors (`venues.json`).\n- **[martj42 international football results](https://github.com/martj42/international_results)** (CC0) — Elo backtesting.\n- **[OpenF1](https://openf1.org)** — keyless live F1 telemetry (runtime source).\n- **[football-data.org](https://football-data.org)** — free football data (runtime source).\n\n## License & author\n\nCreated and maintained by **Utkarsh Gupta** ([@Ninjabeam20](https://github.com/Ninjabeam20)). Licensed under the [MIT License](LICENSE) — © 2026 Utkarsh Gupta. Canonical package: [`sportiq-mcp` on PyPI](https://pypi.org/project/sportiq-mcp/) / `io.github.Ninjabeam20/sportiq-mcp` in the [official MCP registry](https://registry.modelcontextprotocol.io).\n", "bytes": 11670, "sha": "bc9f36b16631814015f959293f86fbb532fdf946d2dafd431860e81a0925899d", "repo_slug": "ninjabeam20/sportiq-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_ninjabeam20_sportiq_mcp_b2d16c4d/readme" }