Sportiq Mcp

sportiq-mcp

MCP 服务可将任何 AI 助手变成体育分析师，覆盖 2026 FIFA 世界杯足球赛、一级方程式赛车和 IPL 板球，提供 46 个可由 AI 调用的工具。

SportIQ 在 Claude 中实时运行 — 蒙特卡洛世界杯淘汰赛模拟、F1 进站策略和 Dream11 优化，每项操作都显示为 MCP 工具调用。(1 分钟演示)

 

所有工具均可免费使用 — 三大旗舰工具以及下方 INTEL 栏中的所有工具，都无需支付 SportIQ 费用或注册账号。实时数据和由数据提供方支持的数据，仍取决于托管方或本地运营者可用的密钥和配额。如果 SportIQ 对你有帮助，请赞助项目，支持持续开发。

v0.4.0 新变化

• 新增两个工具（共 46 个）：
  • f1_simulate_championship：使用精确淘汰计算的冠军争夺蒙特卡洛模拟。
  • football_what_if：从任意阶段重演 2026 世界杯，并可选择翻转一场真实的淘汰赛结果。
• **已完赛赛事模式：**世界杯工具现在会根据 2026 年的真实赛果作答（西班牙在加时赛后以 1–0 赢得决赛），而不是重新模拟。
• **7 个 MCP 资源：**静态参考数据（世界杯抽签结果、球队代码、F1 赛道、IPL 比赛场地和球队、Dream11 计分配置）以及使用说明。
• 准确性修复：
  • 使用 Cricsheet 生成的官方 Dream11 T20 计分规则和 IPL 阵容。
  • F1 进站模型会汇总剩余整个比赛、合法轮胎配方序列和规定比赛距离。
  • 仅提供期望值为正的价值投注。
  • 保留加时赛和点球结果，并支持球队名称和场地解析等更多功能。
• 可靠性：
  • 修复了每分钟左右就会清空缓存的缓存错误。
  • 不再出现每次请求后的清理错误。
  • 新增 /healthz 存活状态路由。
  • 每个工具的截止时间为 30 秒（TOOL_DEADLINE_SECONDS），每条数据链的预算为 15 秒。
  • API 密钥不再出现在日志中。
• 升级：uvx sportiq-mcp@latest 可获取 0.4.0。托管连接器 URL 保持不变。

功能介绍

原始数据工具只是基础；智能分析层才是产品的核心。三大旗舰工具：

• football_simulate_bracket — 基于 48 支球队的 2026 年世界杯赛制，使用泊松 xG 进行蒙特卡洛模拟 → 计算各队晋级各轮及夺冠的概率。
• f1_predict_pit_strategy — 基于 OpenF1 遥测数据的轮胎退化模型 → 计算最佳进站圈数与轮胎配方顺序。
• cricket_build_dream11_team — PuLP 约束求解器 → 在积分、角色和球队限制下生成有效的梦幻 XI 阵容。

工具（共 46 个）

运动项目	原始数据	智能分析
足球（2026 年世界杯）	小组、赛程、积分榜、球队阵容、比赛统计、射手榜、赔率	xg_model、match_predictor、simulate_group、simulate_bracket、knockout_path、form_trends、find_value_bets、build_accumulator、what_if
F1	分站赛、车手、单圈时间、积分榜、比赛结果、天气	tyre_degradation、undercut_window、head_to_head_pace、weather_strategy_impact、qualifying_analysis、race_pace_compare、predict_pit_strategy、simulate_championship
板球（IPL）	实时比赛、记分卡、积分榜、赛程、球队阵容、实时赔率	build_dream11_team、captain_recommendation、differential_picks、player_form_index、pitch_report、head_to_head、player_matchup、find_value_bets
跨运动项目	—	build_accumulator

另有 sportiq_health（计入 46 个工具；提供缓存后端、各适配器状态及剩余 API 配额）。

MCP 资源（静态 JSON，无需调用工具即可读取）：sportiq://instructions、sportiq://football/wc2026/draw、sportiq://football/team-codes、sportiq://f1/circuits、sportiq://cricket/venues、sportiq://cricket/teams、sportiq://cricket/scoring-profile。

数据来源（按链路排列，并提供无需密钥的备用来源）：足球 → API-Football → football-data.org → openfootball（无需密钥）→ 内置的 wc2026.json；积分榜则备用使用根据赛程结果生成的表格。F1 → OpenF1 → Jolpica → fastf1。板球 → CricAPI → RapidAPI Cricbuzz（付费备用来源）+ 静态种子数据（可选择启用 NDTV/Cricbuzz 抓取器）。赔率（足球 + 板球）→ The Odds API。

适用场景

适用于任何支持 MCP 的环境——Claude（桌面版 + 网页版）、ChatGPT、Cursor 及任何 MCP 客户端。提供两种运行方式：

• 托管版（无需安装）： 添加自定义连接器——适用于 claude.ai 网页版和 ChatGPT。
• 本地运行（uvx/桌面版配置/IDE）： 从 PyPI 安装。

工作原理

托管版 — 无需安装

公共实例运行在 Cloudflare 后方的家庭服务器上。将其添加为自定义连接器，并选择 No authentication：

https://sportiq.utkarshgupta.org/mcp

托管历史（GCP Cloud Run → 家庭服务器）：docs/wiki/findings/product-hosting-arc.md。旧的 *.run.app 连接器 URL 已停用。

• claude.ai（网页）： Settings → Connectors → Add custom connector → 粘贴 URL → Save。
• ChatGPT： Settings → Apps & Connectors → 启用 Developer mode → Create app (MCP) → 粘贴 URL → No authentication → Connect。

所有 46 个工具都会在普通 URL 上注册。实时数据或由服务提供商支持的调用能否返回最新数据，取决于托管运营方可用的凭据、配额和回退方案；仓库不会声称公共实例当前拥有哪些密钥。

模式	可用内容
托管版	所有工具都会注册；实时数据或由服务提供商支持的结果取决于主机当前可用的密钥、配额和回退方案。
本地，无密钥	所有工具都会注册；在支持的情况下，可使用捆绑种子数据和无需密钥的数据源，而仅限凭据访问的实时数据源会被跳过。
本地，自带密钥	同一批工具可使用已配置的服务提供商获取更新或实时数据，但受服务提供商配额限制。

托管版 HTTP 边界会拒绝超过 1 MiB 的请求正文，将流量限制为每个客户端每分钟 60 个请求、总计每分钟 300 个请求，并且最多允许两个耗费较高的模型／求解器调用并发执行。这些计数器按进程计算，因此家庭服务器 Compose 堆栈只运行 一个 副本（始终运行，空闲时不产生负载；不会缩容至零）。

本地安装

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 配置：

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

服务器启动后，无需密钥即可注册所有工具。只要具备所需输入，种子数据／无需密钥的回退方案和智能层即可运行；服务提供商密钥可提供更新／实时数据源及配额，而不会解锁单独的付费工具层级。

变量	解锁内容	免费额度
APIFOOTBALL_KEY	实时足球赛程／积分榜／球队阵容／射手榜	100 次请求／天
THEODDS_KEY	市场赔率（足球 + 板球概率工具）	500 次请求／月
FOOTBALLDATA_KEY	football-data.org 回退数据源 — 世界杯端点必需（没有此密钥时会返回 403）	10 次请求／分钟，100 次／天
CRICAPI_KEY	实时板球比分／记分卡／赛程／球队阵容	100 次请求／天
RAPIDAPI_KEY	付费 Cricbuzz 回退数据源（球员生涯统计）	取决于套餐
SPORTIQ_ENABLE_NDTV / SPORTIQ_ENABLE_CRICBUZZ	自选启用的板球抓取器（默认关闭 — ToS）	—
REDIS_URL	共享缓存后端（默认使用本地 diskcache）	—
SPORTIQ_TRANSPORT	stdio（默认，本地）或 http（远程／家庭服务器）	—
TOOL_DEADLINE_SECONDS	单个工具的截止时间（默认 30）；较慢的调用会返回 UPSTREAM_TIMEOUT	—

macOS arm64：Dream11 求解器需要 CBC — brew install cbc（随 PuLP 捆绑的二进制文件仅支持 x86）。

自托管

设置 SPORTIQ_TRANSPORT=http 后，服务器会在 /mcp 提供 MCP 端点（绑定到 0.0.0.0:$PORT）。GET /healthz 仅用于存活检查，会返回 200 ok（不会访问缓存、链或网络）。项目包含可直接构建的 Dockerfile 和家庭服务器 docker-compose.yml。cloud.md 是旧版 Cloud Run 运维手册（历史资料）。设置自己的密钥后，实时比分和赔率工具也会启用。

支持 SportIQ

所有工具均免费且开源 — 原始数据工具、sportiq_health 以及完整的智能层（三大旗舰功能 + INTEL 列中的所有内容）。SportIQ 没有付费功能门槛；但由服务提供商支持的数据仍可能需要运营方提供凭据和配额。

如果 SportIQ 为你节省了时间，请在 github.com/sponsors/Ninjabeam20 赞助该项目，帮助支付托管和持续开发的费用。这是自愿捐赠 — 无论是否捐赠，你都能使用功能完全解锁的同一服务器。

是否安全？

• 开源，采用 MIT 许可，发布于 PyPI，并附有签名的构建证明——连接前请先阅读代码。
• 只读。 工具仅获取和分析公开体育数据，不具备写入、删除、支付、邮件或文件系统工具。
• 有限的运行遥测。 HTTP 模式会记录客户端软件名称/版本、User-Agent、工具名称、结果、延迟、选定的数据源和数据陈旧程度。公共主机（Dell）可能会将 tool_call / mcp_request 记录持久化到本地 JSONL 卷。本地 stdio 会生成本地日志，但不会向 SportIQ 托管的服务发送遥测数据。
• 托管滥用防护。 HTTP POST 请求体上限为 1 MiB；请求速率限制为每个客户端每分钟 60 次、每个进程每分钟 300 次；七个耗费较高的模拟/策略/求解器工具共用并发限制 2；每次工具调用的截止时间为 30 s（TOOL_DEADLINE_SECONDS），每条回退链的总预算为 15 s。
• 凭据感知。 托管运营方可以配置服务提供商凭据；本仓库不声称了解公共实例当前配置的密钥。应用日志和信封中会对密钥进行脱敏。
• 历史自动化 AI 代码审查结果记录在 SECURITY.md 中；这并非当前有效的第三方认证。

每个响应都包含 meta.is_stale 标记和数据年龄，让 AI 告诉你每条回答有多新。板球实时比分约每 30 s 刷新一次，F1 已完成比赛时段的圈速/进站时段数据约每 24 h 刷新一次，排名约每 10 min 刷新一次，足球赛程约每 6 h 刷新一次（2026 年世界杯已结束）。

开发

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

分析仪表板（只读本地使用情况视图——Dell JSONL / 归档的 GCP / PyPI / GitHub）。按上述步骤完成相同设置，然后直接运行：

uv run python scripts/dashboard.py     # writes dashboard.html and opens it; GITHUB_TOKEN optional (Sponsors panel)

注意：仪表板的 HTML 模板（scripts/dashboard_template.html）目前仅供本地维护工具使用，因此新克隆的仓库暂时无法渲染该模板。

仓库布局： src/ 是 MCP 服务（发布到 PyPI，托管于 Dell 上的 https://sportiq.utkarshgupta.org/mcp）；website/ 是部署到 Vercel 的 Next.js 营销网站。两者独立发布——website/ 不包含在 Python 包和后端容器中。

协作规则请参阅 CLAUDE.md，Wiki 入口请参阅 docs/index.md。

数据来源与致谢

SportIQ 使用开放数据集离线推导部分模型常量。原始数据集不会随软件发布，也不会在运行时获取——仓库中只提交少量衍生种子数据（circuits.json、venues.json、elo_seed.json）。

• F1DB（CC BY 4.0）——各赛道的进站次数和单圈长度；进站损失根据 OpenF1 圈速数据离线测得。
• Cricsheet——逐球 IPL 数据 → 衍生的场馆得分先验（venues.json）。
• martj42 国际足球赛果（CC0）——Elo 回测。
• OpenF1——F1 计时数据（运行时来源）。历史比赛时段无需密钥；实时比赛时段遥测需要付费认证，SportIQ 未接入该认证。
• football-data.org——免费足球数据（运行时来源）。

许可证与作者

由 Utkarsh Gupta（@Ninjabeam20）创建并维护。采用 MIT License 授权——© 2026 Utkarsh Gupta。规范的软件包：PyPI 上的 sportiq-mcp / 官方 MCP 注册表中的 io.github.Ninjabeam20/sportiq-mcp。