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