FPL Context

fpl-context-mcp

一个 MCP 服务，为任何支持 MCP 的 AI Agent 提供实时 Fantasy Premier League（FPL）数据：当前比赛周和截止时间、带难度评分的赛程、球员统计和比赛历史、任意经理的阵容和芯片、预期得分，以及伤病和停赛标记。无需任何设置，也不需要数据库：它直接读取公开的 FPL API。可在 Claude Desktop、Claude Code、Cursor、VS Code Copilot、Windsurf、Gemini CLI 和 Codex 中本地运行；ChatGPT 和其他只接受 URL 的客户端，可在你通过 HTTP 托管它后连接。

工具	功能
get_current_gameweek	当前和下一比赛周，以及转会截止时间
get_fixtures	带有 FPL 难度评分（FDR，1 到 5）的赛程：所有球队、某支球队的赛程，或单个比赛周
get_fixture_run	某支球队接下来几场比赛的难度（平均 FDR、主场/客场、空轮和双赛周），或为全部 20 支球队生成排名赛程表
search_players	按姓名、球队、位置和最高价格查找并排列球员；按得分、状态、价格、持有率、预期得分等排序
get_player_history	球员本赛季的比赛记录（可选指定对手），以及过往赛季的赛季总计
get_gameweek_stats	单个比赛周所有球员的统计数据并排名：最高得分、零封、奖励分
get_xpts	按位置、球队和价格估算某比赛周的预期得分，依据底层统计数据、预期出场时间、可用状态和赛程难度计算
get_manager_squad	根据 FPL 球队 ID 获取经理的阵容、队长、替补席、银行余额、转会和已使用的芯片
get_live_availability	所有球员当前的伤病、停赛和可用状态标记

此外还有三个提示词（captain_pick、transfer_plan、chip_timing），会在支持提示词的客户端中显示为斜杠命令；以及一个参考资源（fpl://glossary）。请参阅提示词和资源。

数据限制。 FPL 只提供当前赛季逐场比赛数据；过往赛季的数据为赛季总计。像“X 在过往赛季对阵 Arsenal 时表现如何”这样的问题无法通过 FPL 的数据回答，工具会明确说明，而不会猜测。

---

目录

• 快速开始
• 安装
• 配置
• 在 Claude Desktop 中注册
• 其他 AI 客户端（本地）
• 通过 HTTP 远程访问（ChatGPT 和其他只接受 URL 的客户端）
• 独立运行服务
• 验证连接（--check）
• MCP 工具参考
• 提示词和资源
• 运行测试
• 数据来源和免责声明
• 许可证

---

快速开始

uvx fpl-context-mcp

将它注册到你的客户端（Claude Desktop 配置：{"mcpServers": {"fpl-context": {"command": "uvx", "args": ["fpl-context-mcp"]}}}），然后询问 “这周我应该选谁当队长？” 或 “显示 Arsenal 接下来的五场赛程”。就这么简单：不需要数据库、账户或 API 密钥。

其他客户端请参阅其他 AI 客户端。对于 ChatGPT 和其他只接受 URL 的客户端，请通过 HTTP 托管它。

---

安装

需要 Python 3.11+，并且能够通过 HTTPS 访问 fantasy.premierleague.com。

无需安装（uv）

uvx fpl-context-mcp 可直接从 PyPI 运行。需要安装 uv。

从 PyPI 安装

pip install fpl-context-mcp

这会安装 fpl-context-mcp 命令。

从源码安装

git clone https://github.com/sbanthia92/fpl-context-mcp
cd fpl-context-mcp
pip install -e ".[dev]"

作为其他项目的依赖项

fpl-context-mcp @ git+https://github.com/sbanthia92/fpl-context-mcp.git

---

配置

使用 stdio 时，服务无需配置。以下所有内容仅适用于 HTTP 传输（--transport http），可以设置为环境变量或写入 .env 文件（参见 .env.example）：

变量	默认值	用途
MCP_TRANSPORT / MCP_HOST / MCP_PORT（或 PORT）	stdio / 127.0.0.1 / 8000	--transport / --host / --port 的默认值
MCP_AUTH_TOKEN	（空）	要求访问 /mcp 时提供 Authorization: Bearer <token>。多个密钥以逗号分隔
MCP_RATE_LIMIT_PER_MIN	0（关闭）	/mcp 上每位调用者的请求速率限制；参见远程访问
MCP_CLIENT_IP_HEADER	（空）	可信代理后方客户端真实 IP 所在的请求头

---

在 Claude Desktop 中注册

将服务添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

使用 uvx（推荐）

{
  "mcpServers": {
    "fpl-context": {
      "command": "uvx",
      "args": ["fpl-context-mcp"]
    }
  }
}

如果通过 pip 安装

{
  "mcpServers": {
    "fpl-context": {
      "command": "fpl-context-mcp"
    }
  }
}

如果从源代码运行

{
  "mcpServers": {
    "fpl-context": {
      "command": "python",
      "args": ["/absolute/path/to/fpl-context-mcp/server.py"]
    }
  }
}

提示： 如果使用 uv，请将 "python" 替换为 "uv"，并在 args 前添加 "run"：

"command": "uv",
"args": ["run", "/absolute/path/to/fpl-context-mcp/server.py"]

重启 Claude Desktop。你应该会在工具面板中看到 fpl-context。

---

其他 AI 客户端（本地）

任何能够启动本地 MCP 服务（stdio）的客户端都可以采用相同方式使用：运行 fpl-context-mcp 命令（无需配置）。

Claude Code

claude mcp add fpl-context -- uvx fpl-context-mcp

Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）和 Gemini CLI（~/.gemini/settings.json）使用的 mcpServers 格式与 Claude Desktop 相同：

{
  "mcpServers": {
    "fpl-context": {
      "command": "uvx",
      "args": ["fpl-context-mcp"]
    }
  }
}

VS Code（Copilot Agent 模式） — 工作区中的 .vscode/mcp.json：

{
  "servers": {
    "fpl-context": {
      "type": "stdio",
      "command": "uvx",
      "args": ["fpl-context-mcp"]
    }
  }
}

OpenAI Codex CLI — ~/.codex/config.toml：

[mcp_servers.fpl-context]
command = "uvx"
args = ["fpl-context-mcp"]

尚未安装 uv？ 执行 pip install fpl-context-mcp，然后在上述任一配置中使用 "command": "fpl-context-mcp"（不需要 args）。

你自己的 Agent 代码 — MCP SDK（Python、TypeScript）和 Agent 框架（例如 OpenAI Agents SDK）可以将 fpl-context-mcp 作为 stdio 服务启动，也可以通过 HTTP 连接，如下所示。

---

通过 HTTP 远程访问（ChatGPT 和其他仅接受 URL 的客户端）

有些客户端无法启动本地进程，只接受服务器 URL。其中包括 ChatGPT（Settings → Apps & Connectors → Advanced → Developer mode → create a connector）和 claude.ai 上的自定义连接器。对于这些客户端，请在具有公共 HTTPS 地址的机器上使用可流式 HTTP 传输运行服务器：

MCP_AUTH_TOKEN=some-long-random-string \
fpl-context-mcp --transport http --host 0.0.0.0 --port 8000

• MCP 端点为 https://<your-host>/mcp；GET /health 会返回 ok，供负载均衡器和平台进行健康检查。
• --transport、--host 和 --port 也可以通过 MCP_TRANSPORT、MCP_HOST 和 MCP_PORT 设置（或使用 Render、Cloud Run、Heroku 和 Fly 设置的 PORT 变量）。
• 服务器通过普通 HTTP 侦听。请将它置于负责终止 TLS 的组件之后——上述任一平台都能做到，也可以使用 cloudflared tunnel / ngrok 从自己的机器快速测试。
• 默认绑定地址为 127.0.0.1，因此除非传入 --host 0.0.0.0，否则不会对外开放。

身份验证。 设置 MCP_AUTH_TOKEN 后，每个发往 /mcp 的请求都必须携带 Authorization: Bearer <token>；否则会收到 HTTP 401。允许设置请求头的客户端可以使用此功能，例如 Claude Code：

claude mcp add --transport http fpl-context https://your-host/mcp --header "Authorization: Bearer some-long-random-string"

以及 OpenAI Agents SDK / Responses API MCP 工具（headers={"Authorization": "Bearer ..."}）。

多个密钥。 MCP_AUTH_TOKEN 接受以逗号分隔的密钥列表（key-alice,key-bob）。每位用户都可以拥有自己的密钥；从列表中移除某个密钥即可撤销它，而不影响其他密钥。速率限制按密钥应用。

速率限制和负载。 在公开服务器之前，请先设置以下变量：

变量	默认值	用途
MCP_RATE_LIMIT_PER_MIN	0（关闭）	每位调用者（其 Bearer 令牌，否则为其 IP）每分钟向 /mcp 发出的最大请求数。超过限制时会返回带有 Retry-After 请求头的 429。一次工具调用通常会产生 2-3 个请求，因此请预留余量（120 是一个合理的起始值）。/health 不受限制。计数器存储在内存中，因此运行多个副本时，每个副本都会分别执行自己的限制。
MCP_CLIENT_IP_HEADER	（空）	位于代理之后时，每个请求看起来都来自代理。请将此项设为代理填入真实客户端 IP 的请求头（Fly-Client-IP、CF-Connecting-IP、X-Forwarded-For）。只有在代理会覆盖该请求头时才这样设置；否则，调用者可以伪造 IP 以绕过限制。

ChatGPT 和 claude.ai 连接器仅支持 OAuth 或不进行身份验证，不支持静态 Bearer 令牌。 要使用它们，目前必须不设置 MCP_AUTH_TOKEN（此时任何找到 URL 的人都能访问端点），或在前面部署支持 OAuth 的代理。如果开放运行，任何找到 URL 的人都能使用它并消耗你服务器的 FPL API 流量，因此请设置下方的速率限制。如果服务器绑定到非本地地址且未设置令牌或速率限制，服务器会在启动时记录警告。

要运行公共端点？ 请参阅托管指南：容器、代理设置、身份验证模式，以及每 15 分钟检查一次端点的金丝雀监控。

容器。 项目包含一个 Dockerfile：运行 docker build -t fpl-context-mcp . 进行构建，然后运行它（可选择设置 MCP_AUTH_TOKEN）。它以非 root 用户身份运行，在 $MCP_PORT / $PORT / 8000 上侦听，默认速率限制为每分钟 120 个请求，并会对 /health 进行健康检查。

数据来源。 托管服务器会代表连接的用户调用公共 FPL API，并在内存中缓存响应。无需预先配置或定期更新任何内容。由于现在你会向其他人提供结果，请参阅数据来源和免责声明以及托管指南。

---

独立运行服务

fpl-context-mcp          # installed from PyPI
python server.py         # from source

默认情况下，服务通过 stdio 通信：它的设计用途是由 MCP 客户端启动，直接运行主要用于冒烟测试。若要将其作为持久网络服务运行，请使用 --transport http（参见通过 HTTP 远程访问（ChatGPT 和其他仅支持 URL 的客户端））。

---

验证连接（--check）

fpl-context-mcp --check

确认你的计算机可以访问 FPL API，并在成功时以状态码 0 退出，失败时以状态码 1 退出：

=== fpl-context-mcp check ===

✅ FPL API reachable (700 players, 20 teams)

✅ OK

---

MCP 工具参考

实时工具概览

这些工具直接调用公开的 FPL API，无需数据库或配置。它们共用一个缓存：FPL 的 bootstrap-static 数据（所有球员和球队）只下载一次，并在所有工具间复用 5 分钟；经理的阵容和球员的比赛历史缓存 2 分钟和 5 分钟，已结束比赛周的统计数据缓存 1 小时。如果无法访问 FPL，则返回最后缓存的数据副本，并标注为可能已过期。所有工具均为只读，并声明 readOnlyHint，因此客户端可以跳过审批提示。球队参数接受完整名称、简称或唯一片段（Arsenal、MCI、Man City）。

get_current_gameweek

无参数。返回当前比赛周（进行中或已结束）、下一比赛周，以及距离下一次转会截止时间的剩余时间。"下一个截止时间是什么时候？"

get_fixtures

包含 FPL 难度评级（FDR）的赛程：从各球队自身角度评定，1 最容易，5 最难。

参数	类型	描述
team	字符串	可选。显示该球队的赛程（对手、主场/客场、自身 FDR）。省略则显示所有球队。
gameweek	整数 1-38	可选。指定单个比赛周（比赛结束后包含比分）。
gameweeks_ahead	整数 1-38	可选。列出从下一待进行比赛周开始的比赛周（默认 5）。设置 gameweek 后，此参数将被忽略。

"阿森纳接下来六场比赛的赛程是什么？"、"第 12 比赛周有哪些比赛？"

get_fixture_run

参数	类型	描述
team	字符串	可选。省略则按赛程由易到难排列所有 20 支球队。
gameweeks	整数 1-38	可选。从下一待进行比赛周开始的窗口长度（默认 5）。

查询单支球队时，结果包含平均 FDR、主客场拆分、逐场赛程，以及任何空白或双赛比赛周。"接下来六个比赛周赛程最好的是哪支球队？"、"切尔西接下来的赛程够好吗，值得留住 Palmer 吗？"

search_players

参数	类型	描述
name	字符串	名字、姓氏或网站显示名的一部分。
team	字符串	球队名称或简称。
position	GKP / DEF / MID / FWD	可选。
max_price	数字	最高价格，单位为百万英镑，例如 7.5。
sort_by	字符串	total_points（默认）、form、price、selected_by_percent、ep_next、points_per_game、goals_scored、assists、clean_sheets、minutes、transfers_in_event。按从高到低排序。
limit	整数	返回的行数（默认 15，最多 50）。

每行包含价格、总积分、状态、拥有率、FPL 对下一比赛周的预期积分（ep_next）和可用状态。"状态最佳且价格低于 £8m 的中场球员有哪些？"

get_xpts

参数	类型	描述
position	GKP / DEF / MID / FWD	可选。
team	string	可选。
max_price	number	可选，单位为 £m。
gameweek	integer 1-38	可选。默认为下一个待进行的比赛周。
limit	integer	返回的行数（默认 15，最多 50）。

按球员估算的预期得分（xPts）排序，并显示对手及其 FDR、预期出场时间，以及 FPL 自身的 ep_next。双赛周会计入两场比赛；空白赛周得分为零；FPL 会根据被标记球员的出场概率对其得分进行折减。

xPts 的计算方式。 这是一个简单、透明的基准值，并非预测模型：出场得分，加上球员本赛季每 90 分钟的 xG、xA、零封、扑救和奖励分率乘以 FPL 的计分值，再按预期出场时间（截至目前已出场分钟数占可用分钟数的比例）进行缩放，然后根据 FDR 相对中性值 3 的每分 ±10% 进行调整，并根据出场概率折减。它会依据本赛季至今的数据进行外推，因此在赛季初的几个比赛周内波动较大，也无法预测轮换、战术或定位球安排的变化。可用它生成候选名单，然后通过 get_live_availability 进行交叉核对。“预期得分最高的五名 £8m 以下中场球员有哪些？”

get_player_history

参数	类型	描述
player	string	必填。名字、姓氏或全名（Saka、Bukayo Saka）。如果匹配到多名球员，错误信息会列出他们的名字，方便你进一步指定。
opponent	string	可选。仅返回本赛季对阵该球队的比赛。
last_n	integer 1-40	可选。仅返回最近 N 场比赛。

返回本赛季逐场比赛记录（对手、主场/客场、比分、出场时间、进球、助攻、零封、奖励分、xG、xA、得分）、所示比赛的总计，以及 FPL 留有记录的每个过往赛季的赛季总计。“Haaland 本赛季对阵 Arsenal 表现如何？”、“显示 Saka 最近五场比赛。”

FPL 有哪些数据，以及没有哪些数据。 FPL 仅提供当前赛季的逐场比赛数据。过往赛季则每个赛季只提供一行总计。因此，无法回答“X 过去几个赛季对阵 Arsenal 时表现如何”，工具会明确说明这一点，而不会暗示该球员从未对阵过 Arsenal。

get_gameweek_stats

参数	类型	描述
gameweek	integer 1-38	可选。默认为最近一个已有比赛结果的比赛周。
position	GKP / DEF / MID / FWD	可选。
team	string	可选。
sort_by	string	total_points（默认）、goals_scored、assists、bonus、minutes、expected_goals、expected_assists。按从高到低排序。
limit	integer	返回的行数（默认 15，最多 50）。

列出该比赛周所有有出场时间的球员并进行排名。若比赛周仍在进行中，会特别标明，因为得分和奖励分仍可能变化。“上个比赛周的得分最高者有哪些？”、“GW9 哪些后卫实现了零封？”

get_manager_squad

参数	类型	描述
team_id	integer	经理的 FPL 球队 ID：其 FPL 积分页面 URL 中的数字（fantasy.premierleague.com/entry/<id>/event/<gw>）。
gameweek	integer 1-38	可选。默认为该经理当前所在的比赛周。

返回 15 人阵容及队长和副队长、替补席、银行资金、阵容价值、转会次数和已扣除的转会分、本周使用的芯片，以及本赛季迄今使用过的所有芯片。它仅读取 FPL 已向任何知道球队 ID 的人公开显示的数据；无需登录。“球队 123456 使用过哪些芯片？”

get_live_availability

从 FPL API 实时获取当前的 FPL 伤病、停赛和可上场状态标记。推荐或指定某位球员担任队长前，请先使用此工具，以免遗漏刚刚被标记的球员。

参数（均为可选）

参数	类型	描述
players	字符串数组	要查询的球员姓名，例如 ["Saka", "Haaland"]。不区分大小写；可匹配名、姓或网页显示名称。匹配到的球员即使完全可以上场也会返回。
statuses	字符串数组	仅返回具有这些 FPL 状态代码的球员：a 可上场，d 存疑，i 受伤，s 停赛，u 无法上场，n 未入选名单。

不带参数时，会返回所有当前有状态标记的球员（状态不是 a，或有新闻备注），按新闻发布时间从新到旧排列，最多返回 100 行。每行包含球员、球队、位置、状态、FPL 预测的下一轮出场概率、新闻备注及添加时间。

示例提示词

• “Saka 这轮比赛能上场吗？”
• “过去几天有哪些球员被停赛或确认无法上场？”
• “确定队长人选前，检查 Haaland 和 Salah 是否有状态标记。”

运行方式

• 向 FPL 的 bootstrap-static 端点发送一次请求即可获取所有球员；响应会缓存在内存中 5 分钟，因此频繁使用时，每个服务进程每小时只会向 FPL 发起几次请求。
• 如果无法连接 FPL，会提供最后一份缓存副本，并标注数据可能已过期。如果没有缓存副本，则返回错误。

---

提示词和资源

提示词

预先编写好的工作流。提示词仅包含说明，不包含数据，因此不会过时：运行提示词时，工具会获取实时 FPL 数据。支持 MCP 提示词的客户端会将其显示为斜杠命令（例如，Claude Code 中的 /mcp__fpl-context__captain_pick）。所有参数均为可选；如果未提供 team_id，模型会询问你的阵容，或给出一般性回答。

提示词	参数	功能
captain_pick	team_id、gameweek	使用 get_xpts 为候选球员排序，检查赛程、对手交锋记录和可上场状态，并推荐队长、副队长及一名冷门人选
transfer_plan	team_id、free_transfers、gameweeks	找出你阵容中最弱的资产，在预算范围内比较替代人选的赛程走势和预期得分，并推荐一到两笔转会（以及是否值得扣分）
chip_timing	team_id、chip（wildcard、freehit、bboost、3xc）	查找双赛周和空白赛周，并建议你在何时使用尚未用过的特殊道具

资源

URI	内容
fpl://glossary	FPL 状态代码、FDR、位置、数据限制，以及各工具的用途

---

运行测试

pip install -e ".[dev]"
pytest tests/ -v          # all mocked: no network access needed
ruff check . && ruff format .

---

数据来源和免责声明

fpl-context-mcp 是一个独立的开源项目。它与 Premier League 或 Fantasy Premier League 无关联，也未获得其认可或赞助。

此软件包不附带任何数据。运行时会从你的计算机向以下来源获取数据：

来源	用途	说明
Fantasy Premier League API（fantasy.premierleague.com/api）	球员、球队、赛程、比赛统计数据、经理阵容、伤病／可上场状态新闻	非官方且没有文档；可能随时变更或限制请求速率，恕不另行通知。响应会在内存中缓存几分钟，以减少流量。

你有责任遵守所获取数据的来源使用条款；如果你为其他人托管服务，也有责任遵守相应条款。这对于商业用途和公开部署尤其重要。下方的 MIT 许可证仅适用于本项目代码，不适用于其获取的任何第三方内容。

---

许可证

MIT © 2026 Shubham Banthia