JinDaGe - trainingpeaks-mcp MCP Details

article

README

🚀 TrainingPeaks MCP Server

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

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

🚀 快速开始

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

✨ 主要特性

可实现的功能

使用 TrainingPeaks MCP 与 Claude 的示例对话

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

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

工具特性

| 工具 | 描述 | |------|-------------| | tp_auth_status | 检查认证状态 | | tp_get_profile | 获取运动员资料和 ID | | tp_get_workouts | 按日期范围查询训练课程（计划和已完成的） | | tp_get_workout | 获取单个训练课程的详细指标 | | tp_analyze_workout | 使用时间序列数据、区间和圈数进行详细的训练课程分析 | | tp_create_workout | 创建计划训练课程（日期、运动项目、标题、时长） | | tp_get_peaks | 比较功率个人最佳成绩（5 秒至 90 分钟）和跑步个人最佳成绩（400 米至马拉松） | | tp_get_fitness | 跟踪 CTL、ATL 和 TSB（体能、疲劳度、状态） | | tp_get_workout_prs | 查看特定训练课程中创下的个人记录 | | tp_refresh_auth | 如果会话过期，重新进行认证（从浏览器中提取新的 cookie） |

📦 安装指南

选项 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

登录 app.trainingpeaks.com
打开开发者工具 (F12) → 应用程序 标签 → Cookies
找到 Production_tpAuth 并复制其值
运行 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 存储

| 平台 | 主要存储方式 | 备用方式 | |----------|----------------|----------| | macOS | 系统钥匙串 | 加密文件 | | Windows | Windows 凭据管理器 | 加密文件 | | Linux | 秘密服务（GNOME/KDE） | 加密文件 |

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

Cookie 不会泄露给 AI

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

返回值清理：在将工具结果发送给 Claude 之前，会清除任何包含 cookie、token、auth、credential、password 或 secret 的键。
掩码表示：BrowserCookieResult 和 CredentialResult 类重写了 __repr__ 方法，以显示 cookie=<present> 而不是实际值。
清理异常信息：错误消息仅使用异常类型名称，从不使用可能包含数据的完整消息。
无日志记录：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/令牌发送到除 TrainingPeaks 之外的任何地方 | ❌ 否 | | 向 Claude 暴露你的 cookie | ❌ 否（已清理） | | 打开网络端口 | ❌ 否（仅使用标准输入输出） |

开源

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

src/tp_mcp/auth/browser.py - 带有硬编码域名的 cookie 提取
src/tp_mcp/auth/encrypted.py - AES - 256 - GCM 凭据加密
src/tp_mcp/tools/_validation.py - Pydantic 输入验证
src/tp_mcp/tools/refresh_auth.py - 结果清理
tests/test_tools/test_refresh_auth_security.py - 安全测试

认证流程

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

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

这意味着：

你只需要使用 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

trainingpeaks-mcp