Fantasy Premier League MCP Server

Fantasy Premier League MCP 服务

一个 Model Context Protocol（MCP）服务，可访问 Fantasy Premier League（FPL）数据和工具。借助此服务，你可以在 Claude for Desktop 和其他兼容 MCP 的客户端中与 FPL 数据交互。

Fantasy Premier League MCP 服务运行演示

支持的平台

• Claude Desktop
• Cursor
• Windsurf
• 其他兼容 MCP 的桌面大模型

目前不支持移动设备。

功能

• 丰富的球员数据：访问 FPL API 中全面的球员统计数据
• 球队信息：获取 Premier League 球队的详细信息
• 比赛周数据：查看当前和过往比赛周的信息
• 球员搜索：按姓名或球队查找球员
• 球员比较：比较任意两名球员的详细统计数据

要求

• Python 3.10 或更高版本
• Claude Desktop（用于 AI 集成）

安装

选项 1：从 PyPI 安装（推荐）

pip install fpl-mcp

选项 1b：安装开发依赖项

pip install "fpl-mcp[dev]"

选项 2：从 GitHub 安装

pip install git+https://github.com/rishijatia/fantasy-pl-mcp.git

选项 3：克隆并在本地安装

git clone https://github.com/rishijatia/fantasy-pl-mcp.git
cd fantasy-pl-mcp
pip install -e .

运行服务

安装后，你可以通过以下几种方式运行服务：

1. 使用 CLI 命令

fpl-mcp

2. 使用 Python 模块

python -m fpl_mcp

3. 在 Claude Desktop 中使用

编辑 claude_desktop_config.json 文件，将 Claude Desktop 配置为使用已安装的软件包：

方法 1：直接使用 Python 模块（最可靠）

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "python",
      "args": ["-m", "fpl_mcp"]
    }
  }
}

方法 2：使用已安装命令的完整路径（通过 pip 安装时）

{
  "mcpServers": {
    "fantasy-pl": {
      "command": "/full/path/to/your/venv/bin/fpl-mcp"
    }
  }
}

将 /full/path/to/your/venv/bin/fpl-mcp 替换为可执行文件的实际路径。激活虚拟环境后，在终端中运行 which fpl-mcp 即可查找该路径。

**注意：**仅使用 "command": "fpl-mcp" 可能会导致 spawn fpl-mcp ENOENT 错误，因为 Claude Desktop 可能无法访问虚拟环境的 PATH。使用完整路径或 Python 模块方式可以避免此问题。

用法

在 Claude for Desktop 中

1. 启动 Claude for Desktop
2. 你应该会看到可通过锤子图标访问的 FPL 工具
3. 示例查询：
   • “比较 Mohamed Salah 和 Erling Haaland 过去 5 个比赛周的表现”
   • “查找所有 Arsenal 中场球员”
   • “当前比赛周的状态如何？”
   • “显示得分最高的 5 名前锋”

Fantasy-PL MCP 使用说明

基本命令：

• 比较球员：“比较 [Player1] 和 [Player2]”
• 查找球员：“查找 [Team] 的球员”或“搜索 [Player Name]”
• 赛程难度：“显示 [Team] 即将进行的赛程”
• 队长建议：“[Player1] 和 [Player2] 之间我应该选谁当队长？”

高级功能：

• 统计分析：“比较 [Player1] 和 [Player2] 的底层数据”
• 状态检查：“显示目前状态正佳的球员”
• 冷门选择：“推荐拥有率低于 10% 的冷门人选”
• 球队优化：“为我的球队评分并建议转会”

提示：

• 指定球员姓名，以获得准确结果
• 搜索时注明位置（FWD、MID、DEF、GK）
• 如需最佳队长建议，请询问球员状态、赛程和底层数据
• 要求比较特定指标（xG、禁区内射门等

用于开发的 MCP Inspector

用于开发和测试：

# If you have mcp[cli] installed
mcp dev -m fpl_mcp

# Or use npx
npx @modelcontextprotocol/inspector python -m fpl_mcp

可用资源

• fpl://static/players - 所有球员数据及全面统计信息
• fpl://static/players/{name} - 按姓名搜索球员数据
• fpl://static/teams - 所有英超球队
• fpl://static/teams/{name} - 按名称搜索球队数据
• fpl://gameweeks/current - 当前比赛周数据
• fpl://gameweeks/all - 所有比赛周数据
• fpl://fixtures - 当前赛季的所有赛程
• fpl://fixtures/gameweek/{gameweek_id} - 指定比赛周的赛程
• fpl://fixtures/team/{team_name} - 指定球队的赛程
• fpl://players/{player_name}/fixtures - 指定球员即将到来的赛程
• fpl://gameweeks/blank - 即将到来的空白比赛周信息
• fpl://gameweeks/double - 即将到来的双赛比赛周信息

可用工具

球员

• search_fpl_players - 按姓名搜索球员，可选按位置和球队筛选
• get_player_information - 获取球员详细信息和比赛周历史
• analyze_players - 根据多个条件筛选和分析 FPL 球员
• compare_players - 按各种指标比较多名球员
• get_price_changes - 获取当前比赛周价格上涨或下跌的球员

赛程和比赛周

• get_gameweek_status - 获取当前、上一和下一比赛周的准确信息
• analyze_player_fixtures - 分析球员即将到来的赛程及难度评级
• analyze_fixtures - 分析球员、球队或位置的即将到来的赛程
• get_blank_gameweeks - 获取即将到来的空白比赛周信息
• get_double_gameweeks - 获取即将到来的双赛比赛周信息

实时比赛周

• get_gameweek_live_scores - 比赛进行期间的实时球员得分和统计数据
• get_dream_team - 比赛周官方得分最高的 11 人阵容

你的球队和建议

• suggest_captain - 按队长评分为你的阵容排名，并提供各项评分依据
• check_fpl_authentication - 检查 FPL 身份验证是否正常工作
• update_fpl_credentials - 在聊天中更新已保存的 FPL 凭据
• get_my_team - 查看已验证身份的球队（需要身份验证）
• get_my_current_team - 查看当前比赛周的球队（需要身份验证）
• get_team - 查看指定 ID 的任意球队（需要身份验证）
• get_manager - 获取指定球队 ID 对应的经理详情（需要身份验证）
• get_manager_info - 获取经理详情（需要身份验证）
• get_manager_transfer_history - 获取经理的完整转会记录

联赛

• get_league_standings - 获取经典联赛排名（需要身份验证）
• get_league_analytics - 分析联赛经理、球员持有趋势和表现

提示词模板

• player_analysis_prompt - 创建用于深入分析 FPL 球员的提示词
• transfer_advice_prompt - 根据预算和位置获取球员转会建议
• team_rating_prompt - 创建用于评分和分析 FPL 球队的提示词
• differential_players_prompt - 创建用于寻找持有率低的差异化球员的提示词
• chip_strategy_prompt - 获取关于特殊道具策略的建议

开发

添加功能

要添加新功能：

1. 在 fpl_mcp/fpl/resources/ 中的相应文件里添加资源处理程序
2. 在 fpl_mcp/fpl/tools/ 中的相应文件里添加工具处理程序
3. 更新 __main__.py 文件，以注册新资源和工具
4. 在部署到 Claude for Desktop 之前，使用 MCP Inspector 进行测试

身份验证

FPL 已将登录迁移至 PingOne（Ping Identity）OIDC，因此现在使用 OIDC 刷新令牌进行身份验证，而不是使用电子邮件和密码。刷新令牌会自动交换为 短期访问令牌，且请求会通过 X-API-Authorization: Bearer 标头发送。

如需使用需要身份验证的功能（例如访问你的球队或私人联赛），请设置 刷新令牌：

# Run the credential setup tool
fpl-mcp-config setup

此交互式工具将：

1. 指引你从浏览器复制 OIDC 刷新令牌
2. 提示你输入刷新令牌和球队 ID
3. 将它们（加密后）保存至 ~/.fpl-mcp/credentials.enc

获取刷新令牌：

1. 在浏览器中登录 https://fantasy.premierleague.com。
2. 打开 DevTools 控制台（F12 → Console）并运行：

   copy(JSON.parse(localStorage.getItem(Object.keys(localStorage).find(k=>k.startsWith('oidc.user:')))).refresh_token)
   

   （如果 Chrome 拒绝粘贴，请先在控制台中输入 allow pasting。）刷新 令牌现在已复制到剪贴板——出现提示时粘贴即可。
3. 或者：打开 DevTools → Application → Local storage → https://fantasy.premierleague.com，复制以 oidc.user: 开头的键对应的 完整 JSON 值并粘贴；设置程序会自动提取 refresh_token 字段。

设置完成后立即运行 fpl-mcp-config test：首次交换会在浏览器会话替换令牌之前 先使用该令牌，并轮换令牌，使浏览器中的副本失效——这是预期行为，浏览器会话会 自动恢复。

你可以使用以下命令测试身份验证：

fpl-mcp-config test

或者，也可以手动配置身份验证：

1. 创建 ~/.fpl-mcp/.env 文件，内容如下：

   FPL_REFRESH_TOKEN=your_refresh_token
   FPL_TEAM_ID=your_team_id
   

2. 或创建 ~/.fpl-mcp/config.json：

   {
     "refresh_token": "your_refresh_token",
     "team_id": "your_team_id"
   }
   

3. 或设置环境变量：

   export FPL_REFRESH_TOKEN=your_refresh_token
   export FPL_TEAM_ID=your_team_id
   

注意：FPL 可能会轮换或撤销刷新令牌。如果身份验证开始失败，请使用新复制的令牌 重新运行 fpl-mcp-config setup。

高级：覆盖 OIDC 端点

如果 FPL 更改了 OIDC 客户端或端点，你可以通过环境变量覆盖默认值 （均为可选项）：

变量	默认值
FPL_OIDC_CLIENT_ID	1f243d70-a140-4035-8c41-341f5af5aa12
FPL_OIDC_AUTHORITY	https://account.premierleague.com/as
FPL_TOKEN_URL	<FPL_OIDC_AUTHORITY>/token

限制

• FPL API 没有官方文档，且可能会在不另行通知的情况下发生变更
• 目前仅支持读取操作

故障排除

常见问题

1. Claude Desktop 中出现 "spawn fpl-mcp ENOENT" 错误

这是因为 Claude Desktop 无法在其 PATH 中找到 fpl-mcp 可执行文件。

解决方案： 使用以下任一方法：

• 在配置文件中使用可执行文件的完整路径

  {
    "mcpServers": {
      "fantasy-pl": {
        "command": "/full/path/to/your/venv/bin/fpl-mcp"
      }
    }
  }
  

• 使用 Python 直接运行模块（推荐方法）

  {
    "mcpServers": {
      "fantasy-pl": {
        "command": "python",
        "args": ["-m", "fpl_mcp"]
      }
    }
  }
  

2. 服务立即断开连接

如果服务启动后立即断开连接：

• 检查日志：~/Library/Logs/Claude/mcp*.log（macOS）或 %APPDATA%\Claude\logs\mcp*.log（Windows）
• 确保已安装所有依赖项
• 尝试使用 python -m fpl_mcp 手动运行服务，查看是否有错误

3. Claude Desktop 中未显示服务

如果未出现锤子图标：

• 完全重启 Claude Desktop
• 确认你的 claude_desktop_config.json 使用了正确的 JSON 语法
• 确保 Python 或可执行文件的路径是绝对路径，而非相对路径

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建你的功能分支（git checkout -b feature/amazing-feature）
3. 提交你的更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 提交 Pull Request

更多详情请参阅 CONTRIBUTING.md 文件。

致谢

• 感谢 Fantasy Premier League API 提供数据
• 感谢 Model Context Protocol 提供连接标准
• 感谢 Claude 提供 AI 助手能力

引用

如果您在研究或项目中使用此软件包，请考虑引用它：

@software{fpl_mcp,
  author = {Jatia, Rishi and Fantasy PL MCP Contributors},
  title = {Fantasy Premier League MCP Server},
  url = {https://github.com/rishijatia/fantasy-pl-mcp},
  version = {0.1.0},
  year = {2025},
}