openfoot-mcp

openfoot-mcp

适用于 OpenFootAPI 足球智能 API 的 MCP 服务。为大模型客户端提供真实的足球数据——赛程、积分榜、首发阵容、实时事件、带球场坐标的射门级 xG 以及模型推算的公平赔率——而非幻觉生成的比分。

15 个工具，1 个提示词。Node ≥ 20，无需构建步骤。

安装

npx openfoot-mcp

在环境中设置你的 API 密钥。免费套餐：每月 5,000 次请求。前往 openfootapi.com/pricing 获取密钥。

Claude Desktop / Claude Code

{
  "mcpServers": {
    "openfoot": {
      "command": "npx",
      "args": ["-y", "openfoot-mcp"],
      "env": { "OPENFOOT_API_KEY": "of_live_..." }
    }
  }
}

Cursor / Windsurf / 任意 stdio MCP 客户端

在该客户端的 MCP 配置文件中使用相同代码块。

工具

工具	返回内容
openfoot_competitions	支持的赛事、赛季元数据、每项赛事的数据来源和许可
openfoot_search	自由文本球队／赛事名称 → 稳定 ID
openfoot_matches	赛程和赛果，按日期／赛事／球队／状态／赛季／轮次筛选，使用游标分页
openfoot_standings	某项赛事和赛季的积分榜
openfoot_match_lineups	首发 11 人、替补席、阵型
openfoot_match_events	进球、牌、换人、比赛解说时间线
openfoot_match_xg	每次射门一条记录：球场坐标 + xG 值
openfoot_match_context	衍生背景信息——状态、交锋记录、预计算信号
openfoot_league_xg	联赛 xG 表：预期进球、预期失球，以及相对于实际进球的表现偏差
openfoot_odds	博彩公司基准数据 + 隐含公平概率。仅供参考，不构成投注建议
openfoot_quota	每月剩余配额——调用此工具不会消耗配额
openfoot_health	可访问性检查。无需 API 密钥即可使用

提示词：scout_team_form — 解析球队，获取其最近 5 场比赛，并查看结果背后的 xG。

先使用 openfoot_search 解析 ID。猜测 ID 会浪费配额：404 和空结果与其他请求一样会计入用量。

覆盖范围，如实说明

目录列出了 120 项赛事。覆盖深度并不一致，目录的范围也大于深度覆盖范围。

• 覆盖最深入： Bundesliga、2. Bundesliga、DFB Pokal、Superliga României
• 扩展覆盖的欧洲赛事： Eredivisie、Primeira Liga、Süper Lig、Pro League、Scottish Premiership
• 仅供历史数据／分析使用： Premier League、La Liga、Serie A、Ligue 1（xG 来源于 Understat）

调用 openfoot_competitions 并确认你的联赛后，再基于它构建应用。

配额行为

• 免费套餐：每月 5,000 次请求，每分钟 60 次。Developer 套餐每月 $14：每月 250,000 次请求，每分钟 100 次，包含 xG、射门图、阵容、实时事件和公平赔率。Pro 套餐每月 $39：每月 2,000,000 次请求，每分钟 250 次。
• 不收取超额费用。 配额用尽后，API 会返回 429；此服务会将其作为 quota_or_rate_limit 错误返回，而非空结果。
• 配额于每月 1 日 UTC 时间重置。
• 每次请求都会计入用量，包括 404 和空结果。

以下情况不适合使用此工具

• 对多个赛事进行高频实时轮询。 月度配额不适合此类用途——其他地方按日或按秒计费的方案会更便宜。
• 上述深度覆盖列表以外的联赛。
• 你需要合同 SLA、正常运行时间补偿或指定的支持联系人。 这些价格不包含此类服务。

开发

npm install
npm run smoke   # boots the server over stdio, lists tools, calls health

无需 API 密钥即可运行 npm run smoke：openfoot_health 会返回实时状态，而需要密钥的工具会返回易于理解的 missing_api_key 错误，方便你区分“未配置”和“已损坏”。

MIT。