Fantasy Premier League (FPL)

fpl-mcp

一个开源的英超梦幻联赛 MCP 服务，可与 Claude、ChatGPT、Grok、Cursor、VS Code 及任何其他 MCP 客户端配合使用。它从官方 FPL API 获取实时数据，并从 vaastav 数据集获取 2016-17 赛季起的历史数据，预测每位球员未来五个比赛周的积分，并推荐阵容、转会、队长和特殊道具。数据存储在 SQLite 或 Supabase 中。

无需安装即可试用：

• 远程 URL：https://fpl-mcp-9tiv.onrender.com/mcp（claude.ai、ChatGPT、Grok、Cursor；参见连接 AI 客户端）
• npm：npx -y fpl-mcp-server，适用于运行本地服务的应用（Claude Desktop、Cursor、VS Code）
• Smithery 和官方 MCP Registry（io.github.GilbertKamau/fpl-mcp）

托管服务运行在免费方案上，因此在一段时间没有请求后，首次请求可能需要等待一分钟。

示例问题：“未来 3 个比赛周中，700 万英镑以下的最佳中场球员有哪些？”、 “为球队 1234567 推荐转会”、“这周该使用我的替补席加分吗？”

设置

需要 Python 3.12+。

git clone https://github.com/GilbertKamau/fpl_mcp.git && cd fpl_mcp
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -e ".[supabase,dev]"
fpl-sync all       # load data (~3 min to SQLite; ~15 min to a remote Supabase the first time)
fpl-model all      # train the model and write predictions (~3-6 min the first time)

fpl-sync 任务：

任务	功能	用时
live	球员、价格、伤病、球队、比赛周、赛程	数秒
current	本赛季每位球员的逐场统计数据（FPL API）	约 1 分钟
history	来自 vaastav 的历史赛季（使用 --seasons 2024-25 选择部分赛季）	数分钟，一次
all	以上所有内容
weekly	live + current，然后重新训练并刷新预测	约 5 分钟

fpl-model 任务：evaluate（仅测试）、compare（并排比较特征集）、train、predict、all（训练 + 预测）。 重新加载历史数据后，添加 --refresh-cache，以重建本地历史赛季缓存。

数据库

默认使用 data/fpl.db 中的 SQLite。若要使用 Supabase，请将 .env.example 复制为 .env，并将 Supabase Session pooler 连接字符串粘贴为 DATABASE_URL（直接使用 db.<ref>.supabase.co 主机仅支持 IPv6）。 密码中的特殊字符会自动编码。 数据表会自动创建。

表	内容
players、teams、gameweeks、fixtures	当前赛季快照
player_gameweeks	每个赛季中每位球员每场比赛一行。player_code 用于关联球员的跨赛季数据
season_teams	各赛季的球队 ID → 名称
predictions	每位球员在未来赛程中的预期积分
prediction_history	所有预测记录及其基准数据，用于实时评分
model_artifacts	已训练的模型
model_runs	每次训练的运行记录、测试结果以及是否被接受
sync_log	各项同步任务的运行时间

数据注意事项：2019-20 赛季的比赛周编号延续至 47（COVID 中断后恢复的比赛编号为 39-47）； 2024-25 赛季包含 AM（助理经理）行，模型会忽略这些行；从 2022-23 赛季起提供 xG/xA 数据。

data/（SQLite 备份、缓存、日志）、models/ 和 .env 均已加入 Git 忽略列表，本地 pre-commit 钩子会阻止提交这些内容。

预测模型

LightGBM 根据开赛前可获取的信息，预测每位球员在每场比赛中的得分：

• 状态： 最近 1、3、6、12 和 38 场比赛的滚动平均值（得分、出场时间、首发、xG、xA、奖励分、BPS、ICT、防守贡献……）
• 市场： 该轮的持有率和净转会人数，以百分位表示（大众对球员健康状况和状态的判断）
• 背景： 价格、位置、主客场、距上一场比赛的天数
• 球队实力： 两支球队近期的进球数，以及预期进球（xG）和预期失球

每轮的预期得分是该轮各场比赛的得分之和，因此双赛周会计算两次。 伤病和停赛消息会根据球员出场的可能性，调整其下一轮的预测值。 训练好的模型会存储在数据库中，因此任何机器都可以用它进行预测。

往季测试。 采用滚动前推法：针对最近三个完整赛季中的每个赛季，模型仅使用更早的赛季训练，并预测该赛季的每场比赛。基准值为球员最近 6 场比赛的平均得分。

赛季	模型 MAE	基准 MAE	常规首发球员：模型 / 基准
2023-24	0.931	0.999	2.19 / 2.40
2024-25	0.988	1.053	2.20 / 2.41
2025-26	0.954	1.055	2.26 / 2.55

总体而言，模型比基准值好 7.5%。加入最近一场的状态、整个赛季的状态和市场特征后，平均 MAE 从 0.982 降至 0.958，并且在每个测试赛季中都表现更好（运行 fpl-model compare 可重新测试）。只有在重新训练的模型优于基准值且不逊于当前模型时，才会启用它。

往季测试不包含伤病消息（没有历史记录），因此低估了实时预测准确度。此外，也无法与 FPL 自身的预期得分进行公平比较：历史 xP 列包含伤病消息，而 2025-26 赛季的数值采用了不同的尺度。

实时追踪。 每次预测都会存档。每轮结束后，会将截止时间前做出的预测与实际得分进行比较，并同时对照在同一时刻记录的两个基准值：6 场比赛基准值和 FPL 自身的预期得分（ep_next）。此外，还会比较每种方法排名前 20 的球员实际取得的得分。model_report 会显示持续更新的结果。

FPL 得分存在很大随机性（同样的表现可能得到 2 分，也可能得到 15 分），因此请将预测视为估算值。

优化器

使用 HiGHS（通过 PuLP）求解的整数规划，遵循 FPL 规则：2 名 GKP / 5 名 DEF / 5 名 MID / 3 名前锋，每家俱乐部最多 3 名球员，阵型有效，遵守预算限制，并且超过免费转会次数后每次转会扣 −4 分。之后各轮的得分会按每周 ×0.85 进行折扣，因为越远期的预测越不可靠。

对于经理的球队，只使用公开接口（无需登录）。球员卖出价格根据经理的转会历史估算（FPL 会保留任何价格涨幅的一半），免费转会次数则根据其轮次历史计算（最多可累积 5 次，在使用 Wildcard 和 Free Hit 的轮次也会保留）。自上一个截止时间后进行的转会尚未公开，因此不会纳入计算。

MCP 工具

工具	功能
gameweek_status	当前/下一轮比赛周及截止时间
search_players	按位置、球队、价格、出场分钟数筛选；按任意统计数据排序
get_player	统计数据、伤病消息、最近 6 场比赛、接下来 5 轮比赛周的赛程
compare_players	并排比较 2-6 名球员，包含每 90 分钟数据和价值数据
get_fixtures	某支球队接下来的赛程，或某一整轮比赛周的赛程
team_summary	赛果、进球、零封、赛程安排、顶尖球员
player_season_history	某名球员自 2016-17 赛季以来每个赛季的总数据
get_my_team	按球队 ID 查询任意经理的阵容（公开，无需登录）
predict_points	预测接下来 1-5 轮比赛周的预期得分，并排名
model_report	模型与基线相比的准确度
optimal_squad	根据预算从零开始组建最佳 15 人阵容
suggest_transfers	为球队推荐最佳转会，或建议保留转会次数
pick_captain	队长、副队长及排名前 5 的人选
chip_advice	本半程还剩哪些特殊道具、各自价值多少，以及该使用还是保留
refresh_data	重新获取实时快照

连接 AI 客户端

运行服务有两种方式：

• 本地（stdio）： AI 应用在你的电脑上启动服务。适用于 Claude Code、 Claude Desktop、Cursor 和 VS Code。不会向互联网公开任何内容。
• 远程（HTTP）： 将服务托管在公开的 HTTPS URL 上（参见部署）。 claude.ai、ChatGPT 和 Grok 必须使用此方式，因为它们无法在你的电脑上启动程序。

在以下示例中，/path/to/fpl_mcp/.venv/bin/python 是虚拟环境中的 Python （Windows：C:\path\to\fpl_mcp\.venv\Scripts\python.exe），而 https://your-server.example.com/mcp 是你部署后的 URL。

Claude Code

claude mcp add fpl -- /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server        # local
claude mcp add --transport http fpl https://your-server.example.com/mcp          # remote

Claude Desktop

本地：前往 Settings > Developer > Edit Config，然后添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

远程：使用 Settings > Connectors > Add custom connector（与下文 claude.ai 的方式相同）。

claude.ai

前往 Settings > Connectors > Add custom connector，然后粘贴 https://your-server.example.com/mcp。 付费套餐可用；Team/Enterprise 用户需由所有者为组织添加。claude.ai 可连接无需登录或使用 OAuth 的服务，因此请将 MCP_AUTH_TOKEN 留空。

ChatGPT

开启 Developer mode（Settings > Apps & Connectors > Advanced），使用 URL https://your-server.example.com/mcp 创建连接器，并将身份验证设为 None，然后在聊天中从工具 菜单中选择它。不同套餐的可用性有所不同，请查看 OpenAI 的最新文档。与 claude.ai 一样，它无法 发送固定令牌，因此请将 MCP_AUTH_TOKEN 留空。

Grok（xAI API）

Grok 通过 xAI API 连接远程 MCP 服务：

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client()  # reads XAI_API_KEY
chat = client.chat.create(
    model="grok-4.7",
    tools=[mcp(server_url="https://your-server.example.com/mcp", server_label="fpl")],
)
chat.append(user("Who should I captain in gameweek 7?"))
print(chat.sample().content)

或者使用 Responses API，将以下内容添加到 tools：

{ "type": "mcp", "server_url": "https://your-server.example.com/mcp", "server_label": "fpl" }

如果设置了 MCP_AUTH_TOKEN，也要传入 "authorization": "<token>"。

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

远程：使用 "fpl": { "url": "https://your-server.example.com/mcp" }；如果设置了令牌，还需添加 "headers": { "Authorization": "Bearer <token>" }。

VS Code（GitHub Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "fpl": { "type": "stdio", "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

远程："fpl": { "type": "http", "url": "https://your-server.example.com/mcp" }。

其他客户端

任何支持 stdio 或 Streamable HTTP 的 MCP 客户端都可以使用。若要交互式试用服务： npx @modelcontextprotocol/inspector /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server。

部署

托管服务只会读取数据库。数据处理、训练和预测在你自己的 机器（或任何定时任务）上通过 fpl-sync weekly 运行，托管服务会在 10 分钟内获取新的 预测。因此，你需要一个双方都能访问的数据库，例如 Supabase。

1. 创建只读数据库用户，供公共服务使用：在 Supabase 的 SQL 编辑器中运行 scripts/supabase_readonly_role.sql。

2. **部署。**在 Render 上：选择 New > Blueprint，选取此仓库的分叉， render.yaml 会完成配置。在其他平台（Fly.io、Railway、Google Cloud Run、VPS）上， 使用 Dockerfile。

3. 设置环境变量：

   变量	必需	用途
   DATABASE_URL	是	只读用户的 Supabase Session pooler URI
   MCP_AUTH_TOKEN	否	如果设置，每个请求都需要 Authorization: Bearer <token>。Grok、Cursor 和 VS Code 可以发送此令牌；claude.ai 和 ChatGPT 不支持
   FPL_MCP_ALLOW_REFRESH	否	1 会开放 refresh_data 工具（托管时默认关闭）
   PORT	否	大多数托管平台会自动设置；默认值为 8000

4. 你的 MCP URL 是 https://<your-app>/mcp。https://<your-app>/health 应返回 {"status":"ok"}。

要在本地运行 HTTP 服务：fpl-mcp --http（服务地址为 http://127.0.0.1:8000/mcp）。

没有令牌时，任何拥有此 URL 的人都可以调用这些工具。数据是公开的 FPL 数据，且服务为只读； 但如果 URL 被广泛分享，请设置令牌，或通过托管平台的访问控制来限制访问。

定时更新

GitHub Actions 会保持共享数据库为最新状态：

时间（UTC）	模式	执行内容
星期二 06:00	weekly	刷新数据和结果、重新训练、进行预测
星期五 06:00	news	刷新价格和伤病新闻、进行预测

可在 Actions 选项卡中手动运行（Scheduled update > Run workflow）。这需要一个具有写入权限的仓库密钥 DATABASE_URL，并且只会在主仓库中运行，不会在分叉仓库中运行。若要运行你自己的副本，请将密钥添加到 你的分叉仓库，并修改工作流中的 if: 行。

如果不使用 GitHub Actions，可通过 cron 或 Windows Task Scheduler 运行 fpl-sync weekly（或 fpl-sync live + fpl-model predict）； scripts\update.ps1 可在 Windows 上封装这两种模式，并将日志写入 data\logs。

测试

.venv\Scripts\python -m pytest

路线图

1. 数据处理管道（FPL API + vaastav → SQLite/Supabase）
2. 只读 MCP 工具
3. 积分预测：使用 LightGBM，并通过滚动平均基线进行向前验证（另含与 FPL 自身预期积分的实时跟踪）
4. 优化器：最佳阵容、转会、队长、特殊道具建议
5. 通过 GitHub Actions 定时更新（同步 → 重新训练 → 预测）
6. 为 claude.ai、ChatGPT、Grok 和其他远程客户端提供 HTTP 托管
7. 可选：将更改应用到你的 FPL 球队（默认仅预览）

贡献

欢迎提交问题和拉取请求。提交 PR 前请运行 pytest，并且不要提交 .env、data/ 或 models/。提交贡献即表示你同意依据本项目的 MIT License 授权该贡献。

许可

版权所有 (c) 2026 Gilbert Kamau。根据 MIT License 发布：你可以使用、复制、 修改和分发代码（包括用于商业用途），但须保留版权和许可声明。第三方软件和数据列于 THIRD_PARTY_NOTICES.md。

致谢与免责声明

历史数据来自 vaastav/Fantasy-Premier-League （代码采用 MIT License）；实时数据来自公开的 FPL API。Fantasy Premier League 数据归 Premier League 所有；MIT License 仅适用于本项目代码，不适用于数据。 本项目与 Premier League 或 Fantasy Premier League 没有关联，也未获得其认可。 请负责任地使用 FPL API，并将预测视为估算值，而非保证结果。