whoop-mcp-server

whoop-mcp-server

使用 Go 编写的官方 Whoop API v2 MCP 服务。 将周期、恢复、睡眠、锻炼和个人资料数据作为 MCP 工具提供。

工具

所有工具均返回 JSON。记录结构是未经修改的 Whoop API v2 对象，因此 API 提供的每个字段都可供模型使用。

工具	输入	返回值
get_profile	—	单个对象：user_id、email、first_name、last_name
get_body_measurement	—	单个对象：height_meter、weight_kilogram、max_heart_rate
get_cycles	start_date、end_date、limit（均为可选）	周期记录数组——每个生理日一条记录：start/end、score_state，以及包含当日 strain、kilojoule、average_heart_rate、max_heart_rate 的 score
get_latest_cycle	—	单条周期记录（当前/最近一天）
get_recoveries	start_date、end_date、limit（均为可选）	恢复记录数组——每次睡眠一条记录：cycle_id、sleep_id，以及包含 recovery_score（0–100）、resting_heart_rate、hrv_rmssd_milli、spo2_percentage、skin_temp_celsius 的 score
get_recovery_for_cycle	cycle_id（必需）	该周期的单条恢复记录
get_sleep	start_date、end_date、limit（均为可选）	睡眠记录数组：start/end、nap 标记，以及包含各睡眠阶段时长（浅睡/SWS/REM/清醒，单位为 ms）、respiratory_rate、sleep_performance_percentage、sleep_efficiency_percentage 和睡眠需求明细的 score
get_workouts	start_date、end_date、limit（均为可选）	锻炼记录数组：sport_name、start/end，以及包含锻炼 strain、心率、kilojoule、distance_meter、altitude_gain_meter、各心率区间的时长（zone_durations，每个心率区间的时长，单位为 ms）的 score
get_average_strain	days（可选，默认为 7）	计算得出的汇总：{days, cycles_counted, average_strain}
check_auth_status	—	{authenticated: bool}，成功时附带个人资料，失败时附带 error 字符串

注意：

• 日期格式为 YYYY-MM-DD；end_date 为包含当天（内部会映射到次日开始时间，以符合 API 对排他性 end 的定义）。
• 集合按日期降序排列（最近的在前），并自动分页——服务会持续获取 next_token，直到收集到 limit 条记录（默认 25 条，最多 100 条）。
• 评分是每条记录在某一时点的值，而非时间序列：每个周期一个 strain 值，每次睡眠对应一次恢复数据。要查看趋势，请获取一段时间范围的数据并让模型汇总（也可以使用内置的 strain 平均值工具 get_average_strain）。
• 记录的 score_state 可以是 SCORED、PENDING_SCORE 或 UNSCORABLE——只有当状态为 SCORED 时才会包含 score。

设置

1. 创建 Whoop 开发者应用

在 developer.whoop.com 创建一个应用，并设置：

• 重定向 URI： http://localhost:8719/callback
• 权限范围： read:cycles、read:recovery、read:sleep、read:workout、read:profile、read:body_measurement、offline

记下客户端 ID 和客户端密钥。

2. 安装

Homebrew：

brew install zayden16/tap/whoop-mcp-server

也可以从 Releases 下载预编译的二进制文件，或者：

go install github.com/Zayden16/whoop-mcp-server@latest

或者从源码构建：

go build -o whoop-mcp-server .

3. 授权（仅需一次）

export WHOOP_CLIENT_ID=...
export WHOOP_CLIENT_SECRET=...
./whoop-mcp-server auth

此操作会打开浏览器以进行 OAuth 流程；令牌会保存到 ~/Library/Application Support/whoop-mcp/token.json（macOS），之后会自动刷新 （刷新令牌会轮换）。

4. 在 Claude Code 中注册

claude mcp add whoop --scope user \
  -e WHOOP_CLIENT_ID=... \
  -e WHOOP_CLIENT_SECRET=... \
  -- /path/to/whoop-mcp-server

或者在 Claude Desktop 中，编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "whoop": {
      "command": "/path/to/whoop-mcp-server",
      "env": {
        "WHOOP_CLIENT_ID": "...",
        "WHOOP_CLIENT_SECRET": "..."
      }
    }
  }
}

示例查询

• “我今天的恢复评分是多少？”
• “显示我过去一周的睡眠情况”
• “我过去 7 天的平均负荷是多少？”