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。