WHOOP (read-only)

WHOOP MCP 服务（只读）

向 Claude、Cursor、VS Code 或任何 MCP 客户端询问你的 WHOOP 恢复情况、HRV、睡眠、负荷和锻炼，同时不赋予其更改数据的能力。

_{基于真实 WHOOP 数据给出的真实回答，使用 npm run demo 录制。}

“我昨晚睡得怎么样？为什么我今天的恢复率只有 41%？” “比较一下我过去 30 天的 HRV 和静息心率。” “我这个月跑了多少次？平均负荷是多少？” “负荷超过 15 的日子之后，我的恢复情况会更差吗？”

（安装前后均可执行一次性 auth 步骤。）

为什么选择此服务

• 强制只读。 它只请求 WHOOP 的 read:* 权限范围。HTTP 客户端只能发送 GET，否则测试会导致构建失败，而且每个工具都带有 readOnlyHint: true。
• 一次调用回答完整问题。 get_daily_overview 会一并返回一天的恢复情况、睡眠、小睡、负荷和锻炼。get_trends 会返回最多 90 天的平均值、范围和恢复区间。
• 适合模型处理的输出。 它返回简洁的 JSON，使用小时、km、kcal 和当地时间，而非毫秒和千焦，可节省令牌并避免换算错误。传入 raw: true 可获取 WHOOP 的原始对象。
• 令牌保留在你的设备上。 使用你自己的 WHOOP 开发者应用、权限为 0600 的令牌文件，并安全处理 WHOOP 会轮换的刷新令牌。不经过任何第三方服务。
• 使用当前 API。 基于 WHOOP Developer API v2 构建。
• 经过测试。 单元测试、MCP 集成测试、端到端测试和打包测试均在 Linux、macOS 和 Windows 上使用 Node 20、22 和 24 运行。

快速开始

你需要 Node.js 20.11+ 和 WHOOP 会员资格。

1. 创建 WHOOP 开发者应用（2 分钟）

1. 打开 WHOOP Developer Dashboard，如有提示则创建一个团队。
2. 创建应用：
   • 权限范围： 选择所有 read:* 权限范围（恢复情况、周期、锻炼、睡眠、个人资料、身体测量）。
   • 重定向 URI： http://localhost:8787/callback
3. 复制 Client ID 和 Client Secret。

2. 连接你的 WHOOP 账户

npx -y @oryanomer/whoop-mcp auth

按提示输入 Client ID 和 Client Secret。密钥不会回显，因此不会显示在屏幕上，也不会留在 shell 历史记录中。随后，浏览器会打开 WHOOP 的授权页面。批准后，令牌会保存到 ~/.config/whoop-mcp/tokens.json，之后会自动刷新。

（对于脚本，你可以在环境中设置 WHOOP_CLIENT_ID 和 WHOOP_CLIENT_SECRET，而无需回答提示。）

连接即表示你同意使用条款（EULA）和 WHOOP 的 API 使用条款。有关数据处理方式，请参阅隐私政策。

3. 将其添加到 MCP 客户端

/plugin marketplace add oryanomer1/whoop-mcp
/plugin install whoop@whoop-mcp

claude mcp add whoop --scope user -- npx -y @oryanomer/whoop-mcp

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "@oryanomer/whoop-mcp"]
    }
  }
}

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "@oryanomer/whoop-mcp"]
    }
  }
}

{
  "servers": {
    "whoop": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@oryanomer/whoop-mcp"]
    }
  }
}

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "@oryanomer/whoop-mcp"]
    }
  }
}

[mcp_servers.whoop]
command = "npx"
args = ["-y", "@oryanomer/whoop-mcp"]

docker build -t whoop-mcp https://github.com/oryanomer1/whoop-mcp.git
docker run -i --rm -v ~/.config/whoop-mcp:/home/node/.config/whoop-mcp whoop-mcp

然后提问：“给我看看今天的 WHOOP 概览。”

工具

列表工具接受 start / end（YYYY-MM-DD 或 ISO 日期时间）、days 快捷参数、limit（最多 200，支持自动分页）和 next_token。所有参数和输出示例请参阅**工具参考**。

配置

whoop-mcp            Start the MCP server on stdio (what your MCP client runs)
whoop-mcp auth       Connect your WHOOP account (opens your browser)
whoop-mcp status     Check the stored connection
whoop-mcp logout     Delete the locally stored tokens
whoop-mcp --version

所有命令都通过 npx -y @oryanomer/whoop-mcp <command> 运行，也可以使用 npm install -g @oryanomer/whoop-mcp 全局安装。

隐私与安全

请阅读完整的 隐私政策。简而言之：

• whoop-mcp 只与 api.prod.whoop.com 通信，不会收集遥测数据，也没有中间服务器。
• 令牌和客户端密钥保存在一个只有你的用户才能读取的文件中（0600）。它们绝不会被记录到日志中，也不会由工具返回。
• 你的 MCP 客户端会将工具结果发送给其大模型。 你询问的健康数据会根据模型提供商的条款与其共享，因此请使用你信任的客户端和提供商。
• 若要断开连接，请运行 whoop-mcp logout 删除本地令牌。若要完全撤销访问权限，请在 WHOOP Developer Dashboard 中删除应用或轮换其密钥。

完整的威胁模型见 SECURITY.md。请通过 GitHub 安全公告私下报告漏洞。

身份验证的工作方式

• WHOOP 访问令牌的有效期为一小时。whoop-mcp 会在令牌过期前约一分钟刷新令牌；如果 WHOOP 返回 401，也会再次刷新。
• WHOOP 每次刷新都会签发新的刷新令牌，并拒绝并发刷新。whoop-mcp 会逐个刷新请求，使用锁文件确保同一台机器上的多个客户端（例如 Claude Desktop 和 Claude Code）不会同时刷新，并以原子方式写入新令牌。如果写入失败，新令牌仍保存在内存中，因此磁盘空间耗尽也不会导致你无法登录。
• 对速率限制（429）、WHOOP 服务器错误、超时（每个请求 30s）和网络错误，系统会遵循 Retry-After 并采用退避策略重试。在客户端取消请求后，系统会停止对 WHOOP 的调用。

故障排除

随时检查连接：

npx -y @oryanomer/whoop-mcp status

卸载

npx -y @oryanomer/whoop-mcp logout

然后从 MCP 客户端的配置中移除 whoop 条目；如果不再需要，也请在 WHOOP Developer Dashboard 中删除该应用。

贡献

欢迎提交问题和拉取请求；请参阅 CONTRIBUTING.md。唯一的硬性规则是：whoop-mcp 始终保持只读。发布说明见 CHANGELOG.md。

法律声明

• 许可证： MIT © Oryan Omer
• 使用条款（EULA）： EULA.md。安装或使用 whoop-mcp 即表示你同意这些条款。
• 隐私政策： PRIVACY.md
• 安全政策： SECURITY.md

这是一个非官方项目，与 WHOOP, Inc. 无关联，也未获其认可。“WHOOP” 是 WHOOP, Inc. 的商标。本文内容不构成医疗建议。