JinDaGe - whoop-mcp-server-claude MCP Details

article

README

🚀 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 设置

访问 WHOOP 开发者平台。
创建一个新的应用程序。
记录下你的 客户端 ID 和 客户端密钥。
设置重定向 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 认证。认证步骤如下：

获取授权 URL：使用 whoop-get-authorization-url 工具获取 OAuth URL。
用户授权：引导用户访问授权 URL。
复制授权码：当 WHOOP 将你重定向回来时，从 URL 中复制授权码。
与 Claude 共享代码：重要 - 你必须将授权码直接复制并粘贴到与 Claude 的聊天中。
交换代码：Claude 将使用 whoop-exchange-code-for-token 工具和授权码进行交换。
设置访问令牌：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 端点，请按以下步骤操作：

在 whoop-api.ts 中的 WhoopApiClient 中添加端点方法。
在 types.ts 中添加相应的类型。
在 mcp-server.ts 中添加工具定义和处理程序。

WHOOP API 文档

如需了解 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 文件。

支持

如遇到问题或有疑问，请按以下步骤操作：

查看 WHOOP API 文档。
查看 MCP 服务器的错误消息。
确保你的 OAuth 凭证配置正确。
验证你的访问令牌是否有效且未过期。

迁移通知

重要：WHOOP v2 API 现已可用，需要在 2025 年 10 月 1 日前完成迁移。当前的 v1 API 和 Webhook 将在此日期后停用。此 MCP 服务器使用的是 v2 API。

whoop-mcp-server-claude