Whoop MCP Server Claude

🚀 WHOOP MCP 服務器

WHOOP MCP 服務器是一個模型上下文協議（MCP）服務器，它可讓你訪問所有 WHOOP API 端點。藉助該服務器，你能夠通過 MCP 標準將 WHOOP 的健身和健康數據集成到自己的應用程序中。

✨ 主要特性

• 全面覆蓋 WHOOP API：可訪問所有 WHOOP v2 API 端點。
• OAuth 2.0 認證：提供安全的認證流程。
• 用戶數據：包含用戶的個人資料信息和身體測量數據。
• 生理週期數據：提供生理週期數據，包括壓力和心率指標。
• 恢復數據：涵蓋恢復分數、心率變異性（HRV）和靜息心率數據。
• 睡眠數據：提供詳細的睡眠分析，包括睡眠階段和性能指標。
• 鍛鍊數據：包含鍛鍊數據，如壓力、心率區間和活動指標。
• 分頁支持：支持分頁處理大型數據集。
• TypeScript 支持：具備完整的類型安全和智能感知功能。

📦 安裝指南

1. 安裝依賴項

npm install

2. WHOOP API 設置

1. 訪問 WHOOP 開發者平臺。
2. 創建一個新的應用程序。
3. 記錄下你的 客戶端 ID 和 客戶端密鑰。
4. 設置重定向 URI（例如：http://localhost:3000/callback）。

3. 環境配置

複製示例環境文件並配置你的 WHOOP 憑證：

cp env.example .env

使用你的 WHOOP API 憑證編輯 .env 文件：

# WHOOP API 配置
WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
WHOOP_REDIRECT_URI=http://localhost:3000/callback

# MCP 服務器配置
MCP_SERVER_PORT=3001

4. 構建並運行

# 構建項目
npm run build

# 運行 MCP 服務器
npm start

# 或者以開發模式運行
npm run dev

📚 詳細文檔

認證流程

MCP 服務器支持與 WHOOP 的 OAuth 2.0 認證。認證步驟如下：

1. 獲取授權 URL：使用 whoop-get-authorization-url 工具獲取 OAuth URL。
2. 用戶授權：引導用戶訪問授權 URL。
3. 複製授權碼：當 WHOOP 將你重定向回來時，從 URL 中複製授權碼。
4. 與 Claude 共享代碼：重要 - 你必須將授權碼直接複製並粘貼到與 Claude 的聊天中。
5. 交換代碼：Claude 將使用 whoop-exchange-code-for-token 工具和授權碼進行交換。
6. 設置訪問令牌：Claude 將使用 whoop-set-access-token 工具設置用於 API 調用的訪問令牌。

⚠️ 關於授權碼的重要提示

當你在瀏覽器中完成 WHOOP 授權後，會被重定向到一個包含授權碼的 URL。你必須將此代碼複製並直接粘貼到與 Claude 的聊天中。URL 中的代碼類似如下形式：

http://localhost:3000/callback?code=ABC123XYZ789&scope=read:recovery%20read:cycles...

複製 code 參數的值（例如：ABC123XYZ789），並將其粘貼到與 Claude 的聊天中。Claude 將使用此代碼交換訪問令牌並建立與你 WHOOP 數據的連接。

可用工具

用戶工具

• whoop-get-user-profile - 獲取基本的用戶個人資料信息。
• whoop-get-user-body-measurements - 獲取身體測量數據（身高、體重、最大心率）。
• whoop-revoke-user-access - 撤銷用戶訪問令牌。

生理週期工具

• whoop-get-cycle-by-id - 根據 ID 獲取特定的生理週期數據。
• whoop-get-cycle-collection - 獲取分頁的生理週期列表。
• whoop-get-sleep-for-cycle - 獲取特定生理週期的睡眠數據。

恢復工具

• whoop-get-recovery-collection - 獲取分頁的恢復數據。
• whoop-get-recovery-for-cycle - 獲取特定生理週期的恢復數據。

睡眠工具

• whoop-get-sleep-by-id - 根據 ID 獲取特定的睡眠記錄。
• whoop-get-sleep-collection - 獲取分頁的睡眠記錄。

鍛鍊工具

• whoop-get-workout-by-id - 根據 ID 獲取特定的鍛鍊記錄。
• whoop-get-workout-collection - 獲取分頁的鍛鍊記錄。

OAuth 工具

• whoop-get-authorization-url - 獲取 OAuth 授權 URL。
• whoop-exchange-code-for-token - 用授權碼交換訪問令牌。
• whoop-refresh-token - 刷新訪問令牌。
• whoop-set-access-token - 設置用於 API 調用的訪問令牌。

數據類型

服務器為所有 WHOOP API 響應提供了全面的 TypeScript 類型：

• 用戶數據：個人資料信息、身體測量數據。
• 生理週期：壓力分數、心率數據、千焦消耗。
• 恢復數據：恢復分數、HRV、靜息心率、血氧飽和度（SpO2）、皮膚溫度。
• 睡眠數據：睡眠階段、性能指標、呼吸頻率、效率。
• 鍛鍊數據：活動壓力、心率區間、距離、海拔數據。

分頁

大多數集合端點支持使用以下參數進行分頁：

• limit：返回的記錄數量（最多 25 條）。
• start：開始時間過濾器（ISO 8601 格式）。
• end：結束時間過濾器（ISO 8601 格式）。
• nextToken：下一頁的令牌。

錯誤處理

MCP 服務器包含全面的錯誤處理機制，可處理以下錯誤：

• 無效的憑證。
• 速率限制。
• 網絡錯誤。
• 無效的參數。
• 缺少必需的字段。

開發

項目結構

src/
├── index.ts          # 主入口點
├── mcp-server.ts     # MCP 服務器實現
├── whoop-api.ts      # WHOOP API 客戶端
└── types.ts          # TypeScript 類型定義

可用腳本

• npm run build - 構建 TypeScript 項目。
• npm start - 運行已構建的服務器。
• npm run dev - 以熱重載的開發模式運行。
• npm run watch - 監視更改並重新構建。

添加新端點

要添加新的 WHOOP API 端點，請按以下步驟操作：

1. 在 whoop-api.ts 中的 WhoopApiClient 中添加端點方法。
2. 在 types.ts 中添加相應的類型。
3. 在 mcp-server.ts 中添加工具定義和處理程序。

WHOOP API 文檔

如需瞭解 WHOOP API 的詳細信息，請訪問：

• WHOOP 開發者平臺
• WHOOP API 參考

💻 使用示例

基礎用法

獲取用戶個人資料

// 首先設置你的訪問令牌
await callTool('whoop-set-access-token', { accessToken: 'your_access_token' });

// 然後獲取用戶個人資料
const profile = await callTool('whoop-get-user-profile', {});

獲取近期生理週期

const cycles = await callTool('whoop-get-cycle-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

獲取睡眠數據

const sleepData = await callTool('whoop-get-sleep-collection', {
  limit: 5,
  end: '2024-01-31T23:59:59Z'
});

獲取鍛鍊數據

const workouts = await callTool('whoop-get-workout-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

支持

如遇到問題或有疑問，請按以下步驟操作：

1. 查看 WHOOP API 文檔。
2. 查看 MCP 服務器的錯誤消息。
3. 確保你的 OAuth 憑證配置正確。
4. 驗證你的訪問令牌是否有效且未過期。

遷移通知

重要：WHOOP v2 API 現已可用，需要在 2025 年 10 月 1 日前完成遷移。當前的 v1 API 和 Webhook 將在此日期後停用。此 MCP 服務器使用的是 v2 API。