whoop-mcp

Name: whoop-mcp
Author: rajdeepmondaldotcom

本地服务

github.com/rajdeepmondaldotcom健康医疗220 周前更新

代码仓库

关于 whoop-mcp

whoop-mcp 将 WHOOP 健康记录接入 MCP 客户端，并先计算摘要、趋势和相关性，再由 AI 解释。适合希望通过对话了解恢复、睡眠、负荷和锻炼的 WHOOP 用户；数据与令牌保存在本地。

主要功能

01汇总恢复、睡眠、负荷和锻炼
02分析趋势、训练负荷与相关性
03比较时段并查询个人纪录
04将记录导出为本地 JSON 和 CSV
05提供演示数据、引导设置和诊断

适用场景

01评估每日状态和训练负荷
02探索与恢复相关的因素
03比较不同时段的健康指标
04导出 WHOOP 历史记录以供本地查看

MCP 相关

通过 MCP 工具、资源和提示词提供 WHOOP 数据与分析，也实现 ChatGPT 所需的 search 和 fetch 工具。支持 stdio、HTTP 和 SSE 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "rajdeepmondaldotcom-whoop": {
      "command": "uvx",
      "args": [
        "whoop-mcp-server"
      ],
      "env": {
        "WHOOP_MCP_DEMO": "<WHOOP_MCP_DEMO>"
      }
    }
  }
}

启动命令uvx whoop-mcp-server

需要配置的环境变量

WHOOP_MCP_DEMOSet to 1 to serve realistic generated data (no WHOOP account needed)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiwhoop-mcp-server0.0.5stdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

whoop-mcp-server

WHOOP 会为你展示图表，但它无法回答“我今天应该高强度训练吗？”或“究竟是什么影响了我的恢复？”这个服务可以。

它会将你的 WHOOP 数据连接到 Claude、ChatGPT 和任何 MCP 客户端。你只需用日常英语提问，它就会根据你的个人记录计算答案，并让 AI 为你解读。

You: should I train hard today?

AI:  Recovery 81% (green). HRV trending up. Sleep debt cleared.
     Your 7-day load is 0.94x your 28-day base.
     You are conditioned for more.

在你的设备上运行。只读。唯一的网络通信对象是 api.prod.whoop.com。无遥测。MIT 许可证。

准备事项

一个 WHOOP 账户。任何会员类型都可以。
uv 或 pipx，用于安装一个命令行工具。
一个 MCP 客户端：Claude Desktop、Claude Code、Cursor、Windsurf、VS Code 或 ChatGPT。

开始前需要了解一个限制。WHOOP 没有共享的开发者应用，因此你需要在设置期间创建自己的免费应用。只需点击几下，大约两分钟即可完成。这样设计是为了保护隐私：令牌属于你自己的应用，保存在你的设备上，你的健康数据绝不会经由他人的服务器传输，包括我的服务器。

设置

安装工具：

uv tool install whoop-mcp-server

（pipx install whoop-mcp-server 的效果相同。）

然后运行一条命令，即可完成所有设置：

whoop-mcp-server setup

以下是整个流程，按顺序列出，让你对每一步都心中有数：

你的 WHOOP 应用。 向导会打开 WHOOP 的开发者面板，并准确告诉你要点击什么：创建团队、创建应用、启用所有权限范围，包括 offline，并将重定向 URL 设置为 http://localhost:8765/callback。表单要求填写隐私政策 URL。请使用此仓库的隐私政策：https://github.com/rajdeepmondaldotcom/whoop-mcp-server/blob/main/PRIVACY.md。复制 Client ID 和 Secret，并粘贴到终端中。它们会以 0600 权限保存在本地。
授权。 浏览器会打开 WHOOP 的授权页面。点击批准。令牌会存入 ~/.whoop-mcp，之后会自动刷新。你无需再次操作。
验证。 向导会调用实时 API，并显示你最近一次的实际恢复情况。如果配置有误，你会在这里的终端中发现问题，而不是等到在聊天窗口中才发现。
你的客户端。 向导会检测 Claude Desktop、Cursor、Windsurf、VS Code 和 Claude Code，并为你写入它们的配置。编辑前会备份现有配置。如果 Claude Desktop 正在运行，向导会要求你先退出，因为 Desktop 会在运行期间静默覆盖配置修改。然后，向导会运行一次配置好的命令，并确认服务能够响应。“完成”意味着已经验证，而不是仅仅看起来没问题。

重启客户端并问它：“我昨晚睡得怎么样？”然后再问一个更好的问题：“全面总结一下我本季度的健康状况。”

另外还有两点值得一提。如果你想在连接任何东西之前先看看这些工具的效果，可以运行 whoop-mcp-server serve --demo，通过同一套流程提供 150 天的逼真生成数据。之后如果遇到任何问题，whoop-mcp-server doctor 会指出问题所在并给出修复方法。

你可以询问的内容

24 个工具涵盖 WHOOP API 中所有公开的、用户可读取的端点，以及将记录转化为答案的分析层。

询问	对应工具
“全面了解我的健康状况”	`get_health_overview`：一次调用即可获取状态、趋势、训练负荷、记录和相关性
“我今天状态如何？”	`get_daily_summary`：获取任意一天的恢复、睡眠、负荷和锻炼情况
“哪些因素会实际影响我的恢复？”	`get_correlations`：负荷与次日早晨恢复情况、睡眠与恢复情况之间的关系，并附通俗解读
“我是不是训练过度了？”	`get_strain_trends`：急性与慢性负荷，以及按运动项目细分的情况
“我的 HRV 有改善吗？”	`get_recovery_trends`：趋势方向、置信度和异常日期
“显示我夜间的心率曲线”	`get_sleep_stream`：按分钟记录的心率和皮肤温度、最低点及其出现时间；`include_raw=true` 会保留 WHOOP 未经处理的数据流
“本月和上月相比如何？”	`compare_periods`：列出所有指标及其改善或下降情况
“我今年的个人纪录？”	`get_personal_records`：最佳和最差纪录、连续绿色状态的天数
“导出所有数据”	`export_data`：将完整的历史数据集导出到本地 JSON 和 CSV，默认包含原始记录
周视图网格、原始记录、个人资料	`get_weekly_report`、`get_sleeps/workouts/cycles/recoveries`、带有 `include_raw` 的按 ID 查询工具、`get_profile(include_raw=true)`
“我有一个旧的 WHOOP 活动 ID”	`get_activity_mapping`：将旧版 v1 活动 ID 映射到 v2 UUID
连接问题	`get_connection_status`、`connect_whoop_account`

日期均可使用自然语言表达：昨天、最近 30 天、本周、2 年前、2026-05。

ChatGPT 所需的 search 和 fetch 工具也已实现，另有 4 个资源和 4 个现成的提示词（morning_readiness、weekly_review、sleep_coach、training_planner）。

更多值得提出的问题：docs/PROMPTS.md。

兼容对象

客户端	设置方法
Claude Desktop	`whoop-mcp-server setup` 会为你完成配置。完全无需使用终端：从最新版本下载 `whoop-mcp-server.mcpb` 并打开（需要安装 uv；演示模式可在设置中切换）
Claude Code	`claude mcp add whoop -- whoop-mcp-server serve`（设置程序也会提供此选项）
Cursor	通过设置程序自动配置，或
Windsurf	通过设置程序自动配置
VS Code	通过设置程序自动配置，或
ChatGPT	远程连接器，见下文
Docker	`docker build -t whoop-mcp-server . && docker run -i --rm -e WHOOP_MCP_DEMO=1 whoop-mcp-server`（挂载 `~/.whoop-mcp` 以使用真实数据）
任意 MCP 客户端	`command: whoop-mcp-server`，并设置 `args: ["serve"]`。Inspector：`npx @modelcontextprotocol/inspector whoop-mcp-server serve`

ChatGPT 设置

ChatGPT 连接的是远程 MCP 服务，因此需要公开 HTTP 传输并通过隧道连接：

whoop-mcp-server serve --transport http --port 8000    # endpoint: /mcp
ngrok http 8000

然后在 ChatGPT 中：进入设置、应用和连接器、高级设置，启用开发者模式，创建连接器并填写 https://<your-tunnel>/mcp，无需身份验证。

请务必注意：无身份验证的隧道意味着任何拥有该 URL 的人都可以读取你的健康数据。请对 URL 保密，并缩短隧道的使用时间。Claude 的 stdio 设置不会暴露任何内容。

## 为什么结果可靠

模型大概只占这款产品的 20%。另外 80% 的工作是确保数据准确。模型不擅长对 90 天的记录进行算术运算，因此这个服务会先计算，再让模型进行解释。

趋势线基于按日期排序的序列拟合。WHOOP 返回的记录按时间从新到旧排列。如果按到达顺序拟合，每条趋势都会反着显示。
趋势方向会考虑指标的含义。HRV 上升代表改善，静息心率上升则不然。
记录会根据各自的时区偏移归入日历日期。一次睡眠属于你醒来的那个早晨，即使你当时正在旅行。
WHOOP 每次刷新时都会轮换两个 OAuth 令牌。此处的刷新操作会串行执行、在使用前保存，并在并发请求间共享。重新运行授权即可让正在运行的服务恢复，无需重启。
客户端会遵循 WHOOP 的速率限制标头、进行退避重试，并限制分页数量。如果结果被截断或只是近似值，输出会明确说明，而不会假装结果完整。

它无法做到的事：WHOOP 的公共 API 尚未提供 Peak 功能（例如压力监测器和健康寿命）的端点。WHOOP 发布这些端点后，它们就会加入这里。并非每个账户都启用了夜间传感器数据流；工具会报告这一情况，而不是直接失败。批量导出会有意获取集合端点的数据；原始睡眠数据流可通过 get_sleep_stream(include_raw=true) 按睡眠获取。

105 项测试，全部离线运行，使用模拟的 WHOOP API。CI 覆盖 Python 3.10 至 3.13。

CLI

whoop-mcp-server setup     Guided setup: app, authorize, auto-configure clients
whoop-mcp-server serve     Run the server (--demo, --transport stdio|http|sse, --host, --port)
whoop-mcp-server status    Config and token state
whoop-mcp-server doctor    Diagnose setup and connectivity
whoop-mcp-server auth      Scriptable OAuth flow
whoop-mcp-server logout    Delete tokens (--revoke also revokes at WHOOP)

配置

运行 whoop-mcp-server setup 后无需进行其他配置。覆盖项按优先级排列：进程环境变量、./.env、~/.whoop-mcp/.env、~/.whoop-mcp/config.json。

变量	默认值	用途
`WHOOP_CLIENT_ID` / `WHOOP_CLIENT_SECRET`	无	WHOOP 应用凭据
`WHOOP_REDIRECT_URI`	`http://localhost:8765/callback`	必须与控制面板完全一致
`WHOOP_MCP_DEMO`	关闭	`1` 提供演示数据（等同于 `--demo`）
`WHOOP_MCP_DIR`	`~/.whoop-mcp`	令牌、配置、导出文件
`WHOOP_MCP_TZ`	系统时区	用于确定“今天”和每周范围的 IANA 时区
`WHOOP_MCP_CACHE_TTL` / `WHOOP_MCP_TIMEOUT`	`60` / `30`	秒
`WHOOP_MCP_LOG_LEVEL`	`INFO`	日志输出到 stderr。stdout 留给 MCP
`WHOOP_ACCESS_TOKEN`	无	用于测试的静态令牌，不会刷新

隐私

仅对 WHOOP 执行只读操作。令牌以 0600 权限存储在本地。唯一的写入操作是你要求执行的本地文件写入（export_data）以及你发起的 OAuth 流程。有一点值得注意：趋势和相关性等汇总数据，可能比单条记录透露更多关于你的信息。请只将其连接到你信任其处理健康数据的 AI 客户端。完整政策：PRIVACY.md。漏洞报告：SECURITY.md。

贡献

uv venv && uv pip install -e ".[dev]" && pytest && ruff check .

整个测试套件都可以离线运行。CONTRIBUTING.md 列出了确保数据准确的约束。架构简述：client.py 与 WHOOP 通信，transform.py 清理记录，summaries.py 和 analytics.py 负责计算，server.py 暴露工具。oauth.py 和 tokens.py 负责身份验证。demo.py 是生成的账户。

故障排除

症状	解决方法
“需要 WHOOP 授权”	运行 `whoop-mcp-server setup`，或让你的 AI 连接 WHOOP 账户
授权后重定向失败	控制面板中的重定向 URI 必须与 `http://localhost:8765/callback` 完全一致
`403 missing scope`	在应用中启用所有读取权限范围和 `offline`，然后重新运行 `whoop-mcp-server auth`
客户端中缺少工具	重新运行 `whoop-mcp-server setup`，然后彻底重启客户端
今天未显示恢复情况	WHOOP 会在你醒来并同步后计算分数。摘要中会说明这一点
睡眠数据流“不可用”	WHOOP 并未向每个账户开放此功能。每晚摘要仍可正常使用
其他问题	运行 `whoop-mcp-server doctor`，或在聊天中调用 `get_connection_status`，或提交 issue

许可证

MIT。请参阅 LICENSE。与 WHOOP 无关联，也未获其认可。WHOOP 是 WHOOP, Inc. 的商标。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

whoop-mcp

关于 whoop-mcp

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

whoop-mcp-server

准备事项

设置

你可以询问的内容

兼容对象

CLI

配置

隐私

贡献

故障排除

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？