Football Intelligence MCP

一个本地 Model Context Protocol 服务器，可让任何 MCP 主机——Claude Desktop、Claude Code 或自定义聊天机器人——访问一个精选的历史足球数据库，涵盖 2010 至 2025 年欧洲七大顶级联赛的 36,982 场比赛。

该协议直接基于 JSON-RPC 2.0 实现，未使用任何 MCP SDK：每条消息都按照 2025-06-18 规范手工构建和解析。

数据库内容

数据最初从 API-Football 提取，并规范化到 PostgreSQL 中。

已知覆盖范围限制

服务器会如实报告这些限制而不是猜测，你也应该如此：

• 比赛统计数据始于 2015 年。 2010–2014 赛季包含赛果、进球、事件和首发阵容，但没有射门、控球或传球数据。

• 预期进球（xG）仅从 2023 年起存在，且欧冠联赛从未有该数据。

• 阵型和教练数据始于 2015 年。

• 有 58 场比赛（0.16%）的事件列表中缺少一个进球——这是 API-Football 的上游缺口。比分不受影响；比分来自比赛记录，而非对事件的求和。

调用 data_coverage 工具可查看任何联赛和赛季实际存在的数据。

安装

需要 Python 3.10+ 和 PostgreSQL 14+。

git clone https://github.com/jaq23369/football-intelligence-mcp.git
cd football-intelligence-mcp

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

createdb football
pg_restore -d football data/football.dump

cp .env.example .env      # edit DATABASE_URL if your setup differs

验证恢复：

psql -d football -c "SELECT count(*) FROM fixtures;"
#  count
# -------
#  36982

运行服务器

python server.py

服务器通过 stdio 使用 JSON-RPC 通信。它通常由 MCP 主机启动而非手动运行，但你也可以直接驱动它：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python server.py

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "football": {
      "command": "/absolute/path/to/football-intelligence-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/football-intelligence-mcp/server.py"]
    }
  }
}

Claude Code

claude mcp add football -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

协议

传输方式：stdio，换行分隔的 JSON。协议版本 2025-06-18。

错误遵循 JSON-RPC 2.0：-32700 解析错误、-32600 无效请求、 -32601 方法未找到、-32602 无效参数、-32603 内部错误。

工具级别的失败不是 JSON-RPC 错误——它们返回带有 isError: true 的正常结果，以便模型能够读取消息并恢复。

stdout 只承载 JSON-RPC。 所有诊断信息都输出到 stderr。

工具

search_team

按部分名称查找球队，按记录中的比赛场数排序。请先调用此工具——所有其他球队工具都需要 team_id。

{"name": "search_team", "arguments": {"query": "Liverpool", "limit": 1}}

[{"team_id": 40, "name": "Liverpool", "country": "England",
  "founded": 1892, "partidos": 762,
  "primera_temporada": 2010, "ultima_temporada": 2025}]

search_player

按名称查找球员，按出场分钟数排序。

get_match

完整比赛记录：比分、场地、裁判、各队统计数据以及每个进球及其分钟和助攻。2015 年之前的比赛会返回明确提示，而不是空的统计数据。

get_team_form

近期状态：连胜/连败、积分、进球与失球。

before 将计算限制在严格早于该日期的比赛，这让你可以重建球队在过去任何时刻的状态。这是在构建预测特征时防止前视偏差的保障。

{"name": "get_team_form",
 "arguments": {"team_id": 40, "last": 5, "before": "2020-01-01"}}

get_head_to_head

两队之间的胜/平/负平衡、最近交锋记录，以及双方全部历史交锋中的场均数据（场均进球、黄/红牌、犯规、角球）——这些是决定投注时的有用背景，而不仅仅是一个预测数字。牌/犯规/角球仅对 2015 年起的比赛可用；没有统计数据的比赛会被排除在这些平均值之外，而不是计为零。

get_team_season

最终联赛排名、积分和进球，以及射门、控球、角球和传球成功率的场均数据。

赛季以起始年份命名：2024 表示 2024-25 赛季。

get_player_season

从比赛级记录聚合的球员单赛季数据：进球、助攻、出场分钟、射门、关键传球、牌和平均评分。

compare_teams

一次调用获取两支球队的近期状态及双方交锋记录。

compare_players

两名球员同一赛季的数据并排对比。

data_coverage

按联赛和赛季查看数据库中实际存在的数据。在声称某个数据点缺失之前请先使用它。

predict_match

一场比赛的胜/平/负概率，来自一个在 23,168 场比赛（2015–2025，六个国内联赛——欧冠联赛被排除，其淘汰赛制无法与循环赛积分榜相比）上训练的模型。两个候选模型在一个留出的验证赛季上进行了直接对比（逻辑回归 vs. 梯度提升树分类器）；验证对数损失更优的那个被保留。工具自身响应中的 model.metricas_prueba_2025 字段提供了诚实的、在模型选择过程中从未触碰过的测试分数。

该比赛不需要已经存在于数据库中。每支球队当前的 Elo、近期状态和休息天数保存在 team_current_form 快照中，独立于任何单场比赛刷新——因此这既适用于下周的比赛，也适用于五年前进行的比赛。

{"name": "predict_match", "arguments": {"home_team_id": 529, "away_team_id": 531}}

{
  "local": "Barcelona", "visitante": "Athletic Club",
  "probabilidad_local": 0.779, "probabilidad_empate": 0.145, "probabilidad_visitante": 0.076,
  "modelo": "logistic_regression",
  "advertencia": "Probabilidad estadistica basada en historial, no una garantia..."
}

训练好的模型随附在 data/predict_model.joblib 中（仅几 KB——是一个拟合好的 scikit-learn 流水线，而非原始权重）。重新训练需要完整的特征流水线（conocimiento/ml/），它位于私有项目仓库中，不在这里——这与 data/football.dump 和构建它的提取流水线之间的关系相同。

示例会话

哪支球队赢得了 2015 年的英超联赛？

→ search_team {"query": "Leicester"}
→ get_team_season {"team_id": 46, "league_id": 39, "season": 2015}

莱斯特城，23 胜 12 平 3 负积 81 分——而且场均控球率只有 42.7%，这对冠军来说很不寻常。

架构

MCP host  ──JSON-RPC/stdio──>  server.py  ──>  knowledge/engine.py  ──>  PostgreSQL

server.py 只负责协议，不负责其他任何事。所有查询逻辑都位于 knowledge/engine.py 中，它返回普通字典，并且对 MCP 一无所知——因此它可以完全独立地进行测试或复用。

许可证

MIT。足球数据来源于 API-Football，此处为学术用途而重新分发。

为危地马拉山谷大学 CC3067 Redes 课程构建。