Fantasy Premier League

Fantasy Premier League MCP

一个适用于 Fantasy Premier League 的 MCP 服务，可与任何支持 MCP 的 Agent 搭配使用 — 读取你的阵容和数据、为球员排名、找出差异化选择，并调整你的球队。它已发布到官方 MCP Registry，支持通过 stdio 或远程可流式传输的 HTTP 运行。

此项目在 PyPI 上以 fantasy-premier-league-mcp 发布，而不是 fpl-mcp，后者已被一个无关项目占用。

安装

使用 uv 安装（推荐）：

uv tool install fantasy-premier-league-mcp

也可以不安装，直接运行：

uvx fantasy-premier-league-mcp

fpl_login 还需要本地安装 Chromium。运行以下命令安装一次即可：

uvx --from playwright playwright install chromium

如需开发，请创建虚拟环境并安装项目：

uv sync --group dev
uv run playwright install chromium

发布

推送匹配的版本标签后，GitHub Actions 会发布新版本。 工作流会测试并构建软件包，使用 Trusted Publishing 将其发布到 PyPI，然后将匹配的 server.json 发布到官方 MCP Registry。GitHub 中不会存储 PyPI API 令牌。

首次发布前，请配置一个 PyPI 待处理的 Trusted Publisher，并填写：

• owner：anubabajide
• repository：fpl-mcp
• workflow：release.yml
• environment：pypi
• PyPI 项目：fantasy-premier-league-mcp

创建名为 pypi 的受保护 GitHub 环境（例如，要求手动审批）。完成这项一次性设置后，使用以下命令发布准备好的版本：

git tag v0.3.2
git push origin v0.3.2

Playwright 会驱动一次性浏览器登录，相关说明见“身份验证”部分。

将其连接到你的 Agent

任何支持 MCP 的客户端都可以使用此服务。默认情况下，它通过 stdio 使用 MCP， 也可以作为远程可流式传输的 HTTP 连接器运行，供支持远程 MCP 服务的 Agent 使用。

本地 stdio（推荐）

将 Agent 指向 uvx：

{
  "mcpServers": {
    "fpl": {
      "command": "uvx",
      "args": ["fantasy-premier-league-mcp"]
    }
  }
}

在客户端的 MCP 配置中使用此代码块 — 许多客户端接受 .mcp.json/.cursor/mcp.json 文件，或提供设置界面。有些客户端将顶层键称为 servers，而不是 mcpServers；其中的 fpl 条目相同。对于已检出的副本，将 command 指向项目的 Python，并运行 python -m fpl_mcp。

stdio 模式不会向本机之外公开任何内容。这是最安全的选项。

远程 HTTP

通过 HTTPS 连接远程 MCP 服务的 Agent，可以使用内置的 HTTP 传输方式：

export FPL_MCP_SHARED_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
python -m fpl_mcp --http

然后在其前方设置 HTTPS 隧道（例如 cloudflared tunnel --url http://localhost:8000），并将生成的 https://…/mcp URL 作为自定义连接器提供给 Agent。

如果没有设置 FPL_MCP_SHARED_SECRET（至少 16 个字符），HTTP 模式将拒绝启动。 这些工具可以转会球员并改写你的阵容，因此任何找到该 URL 的人都能通过开放的端点编辑你的球队。每个请求都必须携带 Authorization: Bearer <secret>；否则都会返回 401。连接器运行期间，你的机器必须保持运行。

MCP Bundle

对于以捆绑包形式安装本地 MCP 服务的应用，fpl.mcpb 是一个 zip 文件，其中包含 服务、其依赖项、捆绑的 Python 解释器，以及一个 manifest.json。通过应用的扩展界面安装。有关构建、更新和 Chromium 的详情，请参阅 MCP Bundle 设置说明。

Registry 发现

此服务已在官方 MCP Registry 中列出，标识符为 io.github.anubabajide/fpl，因此支持 Registry 的客户端可以直接找到并安装它。

身份验证

所有只读操作都不需要登录。只有三个写入工具 （fpl_set_lineup、fpl_set_captain、fpl_make_transfers）需要会话。

只需登录一次： 让你的 Agent 运行 fpl_login。它会在运行服务的机器上 打开浏览器窗口，显示 FPL 自己的登录页面，并立即返回：

1. 在该浏览器窗口中登录。
2. 服务会捕获 FPL 发回的重定向，兑换授权码，并自动保存生成的会话——无需 再次调用 fpl_login。

登录会作为独立的后台任务运行，因此即使客户端放弃首次调用，任务也会继续—— 你在窗口中的操作进度不会丢失。登录由你亲自完成；此服务绝不会看到你的密码。 会话以刷新令牌的形式保存在 ~/.fpl-mcp/credentials.json 中，仅你可读取； 访问令牌会通过一次 HTTPS 请求续期。登录后不会再用到浏览器。你不必再操心令牌， 直到会话本身失效；届时，任何写入工具都会提示你再次运行 fpl_login。 fpl_auth_status 可检查浏览器登录是否已完成。

如果无法打开浏览器窗口，fpl_login 会返回状态 awaiting_redirect_url 和一个 sign_in_url。在任意浏览器中打开该链接；登录后， 将最终跳转到的地址作为 redirect_url 传回 fpl_login。

fpl_logout 会清除会话并在 FPL 撤销该会话。fpl_auth_status 会报告当前状态。

为什么不直接保存电子邮件地址和密码？

因为 FPL 的身份提供方拒绝这种交换方式。该网站的 OAuth 客户端 （从 FPL 应用程序包中读取的 bfcbaf69-aade-4c1b-8f00-c1cb8a193030）未配置密码授权：

POST https://account.premierleague.com/as/token
     grant_type=password
  -> 400  unsupported_grant_type: "Invalid grant type: password"

受支持的流程是在浏览器中使用授权码 + PKCE，而 account.premierleague.com 会直接拒绝非浏览器 HTTP 客户端。因此必须在某个环节使用 真正的浏览器。采用这种方式，登录由你在 FPL 自己的页面中通过真正的浏览器窗口完成， 并且此服务绝不会存储、读取或处理任何 FPL 凭据。授权码会使用仅保存在内存中的 PKCE 验证器兑换，之后保存的是刷新令牌——不是密码，也不是浏览器配置文件。

如果登录过程中出现双重验证或机器人检查，你只需像其他登录一样在该窗口中完成验证。 不会绕过任何验证。

备用方案

fpl_set_token 仍接受从 DevTools 手动粘贴的 bearer 令牌，适用于无法启动浏览器的机器。 此类令牌的有效期约为一小时，无法自行续期，并且只会保留到服务停止为止。

工具

设置

工具	功能
fpl_setup	保存你的球队 ID 和默认迷你联赛 ID
fpl_login	在浏览器窗口中登录一次；会话会被记住
fpl_logout	清除已保存的会话
fpl_auth_status	检查会话；如有需要则续期令牌
fpl_set_token	手动粘贴令牌（备用方案）

你的球队

工具	功能
fpl_my_squad	首发 11 人、替补、队长、阵型、银行余额、剩余免费转会次数、持有的芯片
fpl_season_summary	积分、总排名、各比赛周排名、芯片、扣分、过往赛季
fpl_gameweek_report	某比赛周每位球员的得分，包括替补和自动换人；显示实时或已确认的概览
fpl_best_performers	为你自己的阵容排名，查看哪些球员表现出色，哪些是累赘

球员分析

工具	功能
fpl_top_players	游戏中的最佳球员，可按位置、俱乐部和价格筛选；按 metric 或 sort_by 排名
fpl_player	深入了解单名球员：数据、赛程、定位球、伤病消息
fpl_compare_players	并排比较两名或更多球员
fpl_search_players	按名称查找
fpl_fixture_ticker	按即将到来的赛程难度为俱乐部排名

批量导出（用于自行建模）

工具	功能
fpl_export_players	以 CSV 格式紧凑导出球员池——完整球员池或分页导出，不排序
fpl_export_fixtures	导出指定时间范围内的所有赛程，每场比赛中每支球队各占一行
fpl_export_gameweek_history	导出已结束比赛周中每位球员每个比赛周的统计数据

这些工具返回完整数据集，而不是排名靠前的 N 位，因此客户端可以运行自己的优化器。默认使用 CSV：相同数据若使用 JSON，消耗的令牌约为 5 倍。

默认的球员导出内容精简，约有 22 列，可放入工具结果中。fields="standard" 会恢复范围较广的优化器字段（62 列），fields="all" 则提供所有原始字段（112 列），并附带大小警告。可以使用 ids、position、team、min_minutes 或 max_price 进一步缩小范围，也可以通过 offset/limit 分页；响应中包含 has_more 和 next_offset。

按 team_id 将 fpl_export_fixtures 与球员导出数据联接，即可构建每位球员每个比赛周的预测数据。空白周和双赛周会直接体现在数据结构中：某个比赛周没有行表示空白周，有两行则表示双赛周。

球队新闻和阵容

工具	功能
fpl_team_news	按俱乐部提供主教练、新援、离队球员和伤病标记
fpl_predicted_lineups	若已发布则提供确认首发阵容，否则提供推算阵容

主教练数据来自英超联赛自己的 Pulse 后端，并通过 FPL 已提供的 pulse_id 字段与 FPL 数据联接。该接口没有文档，也没有版本控制，因此如果无法获取主教练信息，工具会返回 unknown，而不会导致调用失败。本赛季主教练并非 FPL 资产，因此主教练变动只会间接产生影响——例如轮换、定位球职责和阵型，而不会直接影响积分。

新援和离队球员无需额外数据源：FPL 的 team_join_date 是真实的转会数据源，而其 news 文本会原样包含离队和租借信息。

预测阵容并非任何地方都存在的数据——它属于编辑判断。因此，fpl_predicted_lineups 会返回以下两种结果之一：

• source: "confirmed" — 联赛发布真实球队名单后提供，通常在开球前约一小时；
• source: "predicted" — 基于近期首发、每次出场的分钟数、可出场状态、定位球职责和身价在此推算并排序。每位入选球员都附有 score_breakdown，方便你对权重提出不同看法。

上赛季的先验数据分为比率和出场量，因为总分钟数无法区分“因伤缺阵”和“并非首发球员”。Odegaard 上赛季只首发了 16 场，但每场平均上场 85 分钟，和 Rice 的 88 分钟几乎相同——因此，仅按总数评分会把一位稳固的队长人选排除在首发阵容之外。现在每次首发的上场分钟数比首发次数权重更高，因为球员可能伤愈复出，而球队角色未必改变。

近期加盟的球员则改按转会费评分，因为 7 月加盟的球员在新俱乐部没有出场分钟数，而从国外加盟的球员在任何地方都没有记录。此类数据行会标记为 new_signing。由于这些球员依据缺失的数据而非球员实力评分，任何未能入选首发阵容的新援都会单独列在 new_signings_not_predicted 下——若只按排名处理，他们会排到末尾，看起来像是“未纳入考虑”，但实际情况是“无法评判”。

这些信息无法反映新任主教练的偏好、季前友谊赛或新闻发布会内容。

冷门选择

工具	功能
fpl_differentials	查看两个方向的差异——见下文
fpl_league_standings	查看迷你联赛积分榜和你在其中的排名

更改你的球队（所有操作都会先预览）

工具	功能
fpl_set_captain	更换队长袖标，保持首发阵容不变
fpl_set_lineup	设置完整首发阵容、替补顺序、队长和副队长；可以使用 Bench Boost 或 Triple Captain
fpl_make_transfers	转入和转出球员，可选择使用 wildcard 或 free hit

差异球员的运作方式

fpl_differentials 会按你要求的方式回答两个方向的问题：

• my_differentials — 你拥有、但很少对手拥有的高表现球员。当这些球员得分时，你就能领先其他人。
• differentials_against_me — 你没有、但许多对手拥有的高表现球员。这些球员每次拿高分都会拉低你的排名，因此也可以作为转会候选清单。

提供两种比较范围：

scope="global"                          # vs ownership across all ~7m FPL managers
scope="league", league_id=123456        # vs the top N teams in one mini-league

联赛范围更有参考意义，因为你的迷你联赛排名取决于这些特定对手，而不是整体模板。它会获取每位对手的实际阵容，还会报告有效持有率，其中队长的持有率按双倍计算——如果每位对手都任命某球员为队长，该球员的有效持有率就是 200%，这才是真正的威胁程度。

使用 low_ownership_max（默认值为 10%）和 high_ownership_min（默认值为 20%）调整阈值，并使用 metric= 调整指标（total_points、form、value、xgi、points_per_game、ict_index 等）。

安全性

所有写入工具默认以 dry_run=true 运行。这会验证更改并返回完整预览——变更后的阵容、扣分、之后的银行余额以及任何规则违规——而不会提交任何内容。只有再次调用并设置 dry_run=false 才会实际将更改提交到 FPL。

提交前，服务会根据 FPL 自身的规则检查更改：

• 阵容结构（2 名 GKP / 5 名 DEF / 5 名 MID / 3 名 FWD），且不得有重复球员
• 每家俱乐部最多 3 名球员
• 银行余额充足，并使用你的实际出售价格，而非当前市场价格
• 阵型合法，恰好有一名队长和一名副队长，且两人都在首发阵容中
• 每笔转会的球员位置必须相同
• 替补门将必须安排在正确的替补席位置

如果任何一项检查失败，就不会提交任何内容，而是列出问题。额外转会的扣分根据你实际剩余的免费转会次数计算；使用外卡或免费换人卡时，扣分设为零。

比赛周截止时间

fpl_my_squad 和 fpl_export_fixtures 都会返回下一比赛周的截止时间，采用 FPL 的 UTC 格式，并转换为英国当地时间。数据取自 FPL 自身的 bootstrap deadline_time：

• next_deadline_utc — 例如 2026-11-07T11:00:00Z
• next_deadline_uk / next_deadline_uk_display — 同一时刻的 Europe/London 时间

fpl_export_fixtures 还会列出其时间范围内每个比赛周的 gameweek_deadlines。

更新日志

0.3.2

• 修正 free_transfers / free_transfers_available，使其表示剩余转会次数（FPL's limit 减去已进行的转会），并据此计算扣分，而不是将获得的免费转会次数误当作剩余次数。现在模拟运行会报告正确的扣分，包括本比赛周已进行的转会。
• fpl_set_lineup 现在接受 chip（bboost 或 3xc），并会在提交后报告 FPL 是否确认了该芯片；现在可在模拟运行流程中使用替补席加成和三倍队长。
• 对于正在进行的比赛周，fpl_gameweek_report 现在会返回一致的摘要数据 points、points_on_bench 和 overall_rank，并同时提供已确认的数值和 as_of 标记，而不再混用历史存储数据与实时球员数据行。
• fpl_my_squad 的 chips_available 现在会列出持有的芯片，并通过 active_chip 和 chips_playable_this_gw 显示每个比赛周的情况。
• 转会、阵容和队长工具现在接受球员引用（element id）。
• fpl_top_players 接受 sort_by 作为 metric 的别名。
• fpl_export_players 默认使用精简字段集，并新增 ids、offset 和 limit，使响应符合工具结果限制。
• 新增：fpl_my_squad 和 fpl_export_fixtures 现在会返回比赛周截止时间（next_deadline_utc、英国当地时间）。

关于赛季开始前

在第 1 轮比赛计分之前，FPL API 会一直提供每位球员上赛季的总数据——积分、出场时间、进球数和身价都反映的是上一个赛季，而所有人的 form 都显示为 0.00。工具会在 caveat 字段中标记这一点，避免将这些数据误认为是本赛季的状态。新升入联赛的俱乐部和新签约的球员则完全没有历史数据。

FPL 也不会在第一个截止时间过后才公布任何人的阵容，因此在此之前，fpl_my_squad 和 fpl_differentials 需要通过已登录的会话读取你的草稿阵容，而迷你联赛积分榜则为空。