AI导哈

WHOOP健身数据访问服务器

一个通过Claude和其他MCP客户端无缝访问WHOOP健身和恢复数据的模型上下文协议服务器。

  • by lornest
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 lornest/whoop-mcp

使用说明

WHOOP MCP服务器

MCP（模型上下文协议）服务器，通过Claude和其他MCP客户端无缝访问您的WHOOP健康和恢复数据。

专为 世界卫生组织API v2.

特性

通过对话自然地访问您的WHOOP数据：

  • 身体尺寸：身高、体重和最大心率
  • 生理周期：应变评分和心率指标
  • 恢复数据：恢复评分、心率变异性、静息心率、血氧饱和度和皮肤温度
  • 睡眠分析：睡眠阶段、效率、表现评分和睡眠质量
  • 训练跟踪：运动类型、强度、持续时间、心率区域和距离的活动
  • 自动令牌刷新：无需手动重新身份验证-刷新令牌处理一切

先决条件

快速开始

1.安装依赖项

此项目使用 uv 用于依赖性管理。如果您没有安装它：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

然后同步依赖关系：

uv sync

2.创建WHOOP OAuth应用程序

  1. 访问 WHOOP开发人员仪表板
  2. 创建新应用程序（或使用现有应用程序）
  3. 配置重定向URI： http://localhost:8080/callback
  4. 对于联系人，请添加您的电子邮件地址和隐私政策URL，只需使用https://example.com/privacy，仅供您使用！
  5. 选择所有范围
  6. 注意你的 客户端ID 和 客户端密钥

3.运行Bootstrap脚本

创建 .env 包含OAuth应用程序凭据的文件：

cp .env.example .env

编辑 .env 并添加您的凭据：

WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here

运行引导脚本：

python bootstrap.py

这将：

  1. 打开浏览器以授权应用程序
  2. 启动本地web服务器以接收OAuth回调
  3. 交换访问和刷新令牌的授权码
  4. 输出完整的MCP服务器配置 准备复制

4.添加到您的MCP客户端

引导脚本输出一个配置块。复制它并将其添加到您的MCP客户端：

对于Claude Desktop：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

配置如下：

{
  "mcpServers": {
    "whoop": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/whoop-mcp",
        "run",
        "main.py"
      ]
    }
  }
}

注： 令牌被安全地存储（操作系统密钥链或加密文件）-不需要环境变量！

重新启动克劳德桌面 您已经准备好使用WHOOP MCP服务器了！

高级配置

手动测试（无MCP客户端）

要独立运行服务器进行测试，请执行以下操作：

uv run main.py

手动OAuth流

如果您更喜欢手动处理OAuth而不是使用引导脚本：

授权URL: https://api.prod.whoop.com/oauth/oauth2/auth

令牌URL: https://api.prod.whoop.com/oauth/oauth2/token

所需范围： read:profile read:cycles read:recovery read:sleep read:workout offline

有关OAuth设置的详细信息，请参阅 WHOOP OAuth文档.

你能问什么？

配置后，您可以通过Claude自然地与您的WHOOP数据交互：

  • “今天早上我的康复分数是多少？”
  • “显示我上周的睡眠数据”
  • “这个月我做了多少次锻炼？”
  • “过去30天我的平均HRV是多少？”

你甚至可以问更复杂的问题，比如：

  • “分析我过去两周的睡眠和锻炼数据。我的恢复模式是什么？”

或者结合谷歌日历等其他工具的数据，看看你的锻炼和恢复是如何与你的日程安排相一致的。

可用工具

get_user_profile（）

获取经过身份验证的用户的身体测量数据，包括：

  • 高度（米）
  • 重量（公斤）
  • 最大心率（bpm）

get_recent_cycles（天数=7）

获取过去N天的生理周期（默认值7）。

参数：

  • days （int）：回顾的天数

退货： 周期数据，包括应变、心率和恢复评分

get_recent_recovery（天数=7）

获取过去N天的恢复数据。

参数：

  • days （int）：回顾的天数

退货： 恢复评分、心率变异性、静息心率、血氧饱和度和皮肤温度

get_recent_sleep（天数=7）

获取过去N天的睡眠数据。

参数：

  • days （int）：回顾的天数

退货： 睡眠阶段、效率、表现、睡眠需求和呼吸频率

get_recent_workouts（天数=7）

获取过去N天的锻炼数据。

参数：

  • days （int）：回顾的天数

退货： 具有运动类型、压力、持续时间和心率区域的锻炼活动

get_cycles_for_date_range（开始日期、结束日期、限制=25）

获取特定日期范围的周期。

参数：

  • start_date （str）：ISO 8601格式的日期（例如，“2024-01-01T00:00:00.000Z”）
  • end_date （str）：ISO 8601格式化日期
  • limit （int）：要返回的最大记录数（默认值25，最大值50）

get_sleep_for_date_range（起始日期、结束日期、限制=25）

获取特定日期范围的睡眠数据。

参数：

  • start_date （str）：ISO 8601格式化日期
  • end_date （str）：ISO 8601格式化日期
  • limit （int）：要返回的最大记录数（默认值25，最大值50）

get_workout_for_date_range（开始日期、结束日期、限制=25）

获取特定日期范围的锻炼数据。

参数：

  • start_date （str）：ISO 8601格式化日期
  • end_date （str）：ISO 8601格式化日期
  • limit （int）：要返回的最大记录数（默认值25，最大值50）

API版本

此服务器使用 世界卫生组织API v2.请注意，WHOOP API的v1将于 2025年10月1日.

数据类型

循环

表示生理周期（不是日历日），包括：

  • 开始和结束时间
  • 应变分数和千焦
  • 平均和最大心率
  • 恢复数据（如果可用）

恢复

日常准备指标包括：

  • 恢复百分比（0-100）
  • HRV RMSSD（毫秒）
  • 静息心率（bpm）
  • 血氧饱和度百分比（仅WHOOP 4.0）
  • 皮肤温度（摄氏度）

睡眠

睡眠会话数据包括：

  • 睡眠阶段（浅波、深波/慢波、REM、清醒）
  • 睡眠表现和效率百分比
  • 睡眠需求计算
  • 呼吸频率
  • 干扰计数

锻炼

锻炼活动数据包括：

  • 运动名称和ID（100+支持的活动）
  • 应变评分
  • 持续时间和距离
  • 心率区域（5个级别）
  • 海拔高度和千焦

安全功能

此服务器遵循MCP安全最佳实践，并使用行业标准的安全存储：

安全令牌存储

令牌是使用您平台的最佳可用方法存储的：

  • macOS：存储在macOS钥匙串中的令牌
  • 视窗：存储在Windows凭据锁中的令牌
  • Linux：存储在GNOME Keyring/KWallet中的令牌
  • 后备方案：使用Fernet对称加密的加密文件存储

您的客户端机密从未包含在MCP配置中 -它仅存储在安全存储中，并在内部用于令牌刷新操作。

OAuth 2.0/2.1合规性

此服务器使用 authlib，一个经过充分测试的OAuth库，遵循MCP的指导：

不要自己实现令牌验证或授权逻辑。使用现成的、经过良好测试的、安全的库

优点：

  • ✅ 符合标准的OAuth 2.0/2.1实现
  • ✅ 自动令牌到期跟踪
  • ✅ 主动令牌刷新（令牌在到期前刷新，而不是在失败后刷新）
  • ✅ 无自定义加密或验证逻辑

令牌存储位置

  • OS钥匙扣：服务名称 whoop-mcp-tokens
  • 目标文件: ~/.whoop_mcp/tokens.enc （回退）

自动令牌刷新

WHOOP访问令牌是短暂的（通常为几个小时）。此服务器自动处理令牌刷新：

  1. 主动刷新 -令牌在到期之前刷新，而不是在到期之后
  2. 自动持久化 -更新的令牌会自动保存到安全存储中
  3. 服务器重启后仍能存活 -启动时从安全存储加载令牌
  4. 无人工干预 -一切都是透明的

如果令牌刷新失败（例如，刷新令牌在数月不活动后过期），您需要使用 python bootstrap.py.

错误处理

服务器包括全面的错误处理：

  • 缺少访问令牌将引发一条明确的错误消息
  • 过期的令牌将使用刷新令牌自动刷新
  • 来自WHOOP API的HTTP错误将与有用的消息一起传播
  • 明确识别速率限制错误（429）
  • 捕获并报告网络错误
  • 无效的日期范围将由API处理

速率限制

世卫组织API有费率限制。如果遇到速率限制错误：

  • 减少请求的频率
  • 使用日期范围查询，而不是多个最近的查询
  • 对频繁访问的数据实施缓存
  • 服务器将清楚地报告速率限制错误

贡献

欢迎投稿！请确保：

  • 代码遵循现有样式
  • 新功能包括文档字符串
  • 错误处理是适当的

许可证

本项目按原样提供，供WHOOP API v2使用。

资源

相关 MCP