Trainingpeaks MCP

🚀 TrainingPeaks MCP Server

通过模型上下文协议（MCP）将 TrainingPeaks 与 Claude 及其他 AI 助手连接起来。通过自然对话查询你的训练课程、分析训练负荷、比较功率数据并跟踪体能趋势。

无需 API 审批。官方 Training Peaks API 需要审批，但此服务器使用安全的 cookie 身份验证，任何用户都可以在几分钟内完成设置。你的 cookie 存储在系统密钥环中，除了 TrainingPeaks 之外，不会传输到任何地方。

🚀 快速开始

通过模型上下文协议（MCP）将 TrainingPeaks 与 Claude 和其他 AI 助手相连，你可以通过自然对话的方式查询训练课程、分析训练负荷、比较功率数据并跟踪体能趋势，且无需 API 审批。以下为你介绍具体使用步骤。

✨ 主要特性

可实现的功能

你可以向 AI 助手提出以下问题：

• “比较我今年和去年的 FTP 增长情况”
• “在我达到最佳 20 分钟功率前的 6 周里，我的 TSS 增长率是多少？”
• “我是否准备好参赛？展示我的体能趋势和近期训练课程质量”
• “我通常一周中哪几天训练最刻苦？”
• “找出我 TSS 超过 800 的周次，并展示之后我的体能状况”

工具特性

📦 安装指南

选项 A：使用 Claude Code 自动设置

如果你有 Claude Code，粘贴以下提示：

从 https://github.com/JamsusMaximus/trainingpeaks-mcp 设置 TrainingPeaks MCP 服务器 - 克隆它，创建虚拟环境，安装它，然后指导我从浏览器中获取我的 TrainingPeaks cookie 并运行 tp-mcp auth。最后，将其添加到我的 Claude Desktop 配置中。

Claude 将处理安装过程，并逐步指导你完成认证。

选项 B：手动设置

步骤 1：安装

git clone https://github.com/JamsusMaximus/trainingpeaks-mcp.git
cd trainingpeaks-mcp
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

步骤 2：认证

选项 A：从浏览器自动提取（最简单） 如果你已在浏览器中登录 TrainingPeaks：

pip install tp-mcp[browser]  # 一次性操作：安装浏览器支持
tp-mcp auth --from-browser chrome  # 或者：firefox, safari, edge, auto

macOS 注意事项：你可能会看到关于钥匙串或全盘访问的安全提示。这是正常的 - 浏览器 cookie 是加密的，需要权限才能读取。

选项 B：手动输入 cookie

1. 登录 app.trainingpeaks.com
2. 打开开发者工具 (F12) → 应用程序 标签 → Cookies
3. 找到 Production_tpAuth 并复制其值
4. 运行 tp-mcp auth 并在提示时粘贴

其他认证命令：

tp-mcp auth-status  # 检查是否已认证
tp-mcp auth-clear   # 删除存储的 cookie

步骤 3：添加到 Claude Desktop

运行以下命令以获取配置片段：

tp-mcp config

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），并将其粘贴到 mcpServers 中。多个服务器的示例如下：

{
  "mcpServers": {
    "some-other-server": {
      "command": "npx",
      "args": ["some-other-mcp"]
    },
    "trainingpeaks": {
      "command": "/Users/you/trainingpeaks-mcp/.venv/bin/tp-mcp",
      "args": ["serve"]
    }
  }
}

重启 Claude Desktop。你就可以开始使用了！

💻 使用示例

基础用法

以下是使用各个工具的示例：

tp_get_workouts

列出指定日期范围内的训练课程。每次查询最多 90 天。

{ "start_date": "2026-01-01", "end_date": "2026-01-07", "type": "completed" }

tp_get_workout

获取单个训练课程的完整详细信息，包括功率、心率、踏频、TSS。

{ "workout_id": "123456789" }

tp_analyze_workout

获取详细的训练课程分析，包括指标、区间和圈数数据。完整的时间序列数据将保存到 JSON 文件中以供进一步分析。

{ "workout_id": "123456789" }

tp_create_workout

在指定日期创建计划训练课程。

{ "date": "2026-02-01", "sport": "Run", "title": "Easy 5K", "duration_minutes": 30 }

运动项目：Bike、Run、Swim、Strength、DayOff、Other 可选字段：description（最多 2000 个字符）、distance_km、tss_planned

tp_get_peaks

获取排名的个人记录。自行车：功率指标。跑步：配速/速度指标。

{ "sport": "Bike", "pr_type": "power20min", "days": 365 }

自行车类型：power5sec、power1min、power5min、power10min、power20min、power60min、power90min、hR5sec、hR1min、hR5min、hR10min、hR20min、hR60min、hR90min 跑步类型：speed400Meter、speed800Meter、speed1K、speed1Mi、speed5K、speed5Mi、speed10K、speed10Mi、speedHalfMarathon、speedMarathon、speed50K、hR5sec、hR1min、hR5min、hR10min、hR20min、hR60min、hR90min

tp_get_fitness

获取一段时间内的训练负荷指标。

{ "days": 90 }

或者，查询特定日期范围：

{ "start_date": "2025-01-01", "end_date": "2025-03-31" }

返回每日 CTL（慢性训练负荷/体能）、ATL（急性训练负荷/疲劳度）和 TSB（训练压力平衡/状态）。

tp_get_workout_prs

获取特定训练课程中创下的个人记录。

{ "workout_id": "123456789" }

📚 详细文档

什么是 MCP？

模型上下文协议 是一种将 AI 助手连接到外部数据源的开放标准。MCP 服务器提供 AI 模型可以调用的工具，以获取实时数据，使 Claude 等助手能够通过自然语言访问你的 Training Peaks 账户。

安全性

简而言之：你的 cookie 在磁盘上加密存储，会交换为短期的 OAuth 令牌，不会显示给 Claude，并且只会发送到 TrainingPeaks。服务器没有网络端口。

此服务器采用深度防御设计。你的 TrainingPeaks 会话 cookie 很敏感 - 它可以访问你的训练数据 - 因此我们会相应地处理它。

写入权限：tp_create_workout 可以创建计划训练课程。所有其他工具都是只读的。服务器不能修改或删除现有的训练课程。

Cookie 存储

你的 cookie 永远不会 以明文形式存储。加密文件备用方式使用 AES - 256 - GCM 认证加密，使用 PBKDF2 派生的密钥（600,000 次迭代）和特定于机器的盐。

Cookie 不会泄露给 AI

AI 助手（Claude）永远不会看到你的 cookie 值。多层防护确保了这一点：

1. 返回值清理：在将工具结果发送给 Claude 之前，会清除任何包含 cookie、token、auth、credential、password 或 secret 的键。
2. 掩码表示：BrowserCookieResult 和 CredentialResult 类重写了 __repr__ 方法，以显示 cookie=<present> 而不是实际值。
3. 清理异常信息：错误消息仅使用异常类型名称，从不使用可能包含数据的完整消息。
4. 无日志记录：Cookie 值永远不会写入任何日志。

域名硬编码（不可更改）

浏览器 cookie 提取 仅 访问 .trainingpeaks.com：

# From src/tp_mcp/auth/browser.py - HARDCODED, not a parameter
cj = func(domain_name=".trainingpeaks.com")

Claude 无法通过工具参数修改此设置。唯一的参数是 browser（chrome/firefox 等），而不是域名。要更改域名，需要修改源代码。

只读访问

此服务器对 TrainingPeaks 提供 有限的写入 访问权限：

• ✅ 查询训练课程、体能指标、个人记录
• ✅ 创建计划训练课程
• ❌ 不能修改或删除现有的训练课程
• ❌ 不能更改账户设置
• ❌ 不能访问账单或支付信息

无网络暴露

MCP 服务器仅使用 标准输入输出传输 - 它通过标准输入/输出与 Claude Desktop 通信，而不是通过网络。没有 HTTP 服务器，没有开放端口，没有远程访问。

此服务器无法完成的操作

开源

此服务器是完全开源的。你可以在运行之前审核每一行代码。关键安全文件：

• - 带有硬编码域名的 cookie 提取
• - AES - 256 - GCM 凭据加密
• - Pydantic 输入验证
• - 结果清理
• - 安全测试

认证流程

服务器使用两步认证过程：

1. Cookie → OAuth 令牌：你存储的 cookie 会交换为短期的 OAuth 访问令牌（有效期 1 小时）
2. 自动刷新：令牌会缓存在内存中，并在过期前自动刷新

这意味着：

• 你只需要使用 tp-mcp auth 进行一次认证
• API 调用使用正确的 Bearer 令牌认证，而不是 cookie
• 如果你的会话 cookie 过期（通常在几周后），在 Claude 中使用 tp_refresh_auth 或再次运行 tp-mcp auth

开发

pip install -e ".[dev]"
pytest tests/ -v
mypy src/
ruff check src/

📄 许可证

MIT