WHOOP Health Signals

mcp-server-whoop

一个本地优先、只读的 WHOOP 模型上下文协议服务。它为兼容 MCP 的 AI 客户端提供简明的恢复、睡眠、负荷、HRV、心率、锻炼和身体测量数据，且不会通过托管的第三方发送你的 WHOOP 凭据。

为什么选择此服务

• 通过标准 MCP stdio 提供服务，可供任何支持本地 MCP 服务的客户端使用
• 使用每位用户自己的 WHOOP 开发者应用进行本地 WHOOP OAuth 授权
• 访问令牌和轮换刷新令牌均保留在用户的设备上
• 提供五个专注的只读工具，而非杂乱的 API 数据转储
• 每条记录均带有本地时间戳，因此旅行不会导致睡眠或锻炼日期偏移
• 明确显示 processing 状态；新睡眠数据尚未就绪时，不会使用较早的恢复数据替代
• 仅为 SCORED 记录提供基于评分的指标；当前周期的实时负荷标记为 provisional_strain
• 以便于理解的小时、分钟、卡路里和心率区间分钟数呈现数据
• 工具输出不包含原始标识符、OAuth 密钥或原始连续心率数据
• 不使用托管中继、遥测、数据库、通用 HTTP 工具、原始 SQL 或安装生命周期脚本
• 提供可复现的 tarball 安全审计、CycloneDX SBOM、CodeQL、Gitleaks、依赖项审查和 OpenSSF Scorecard

这是一个独立的社区项目，与 WHOOP 无关，也未获 WHOOP 认可。WHOOP 数据可用于辅助指导，但不能替代医疗建议。

要求

• Node.js 18 或更高版本
• WHOOP 账户
• 在 WHOOP Developer Dashboard 中创建的免费应用
• 兼容 MCP 的 AI 客户端

快速开始

1. 创建 WHOOP 开发者应用，并注册 http://127.0.0.1:8765/callback。
2. 启用下方列出的五个读取权限范围和 offline。
3. 在终端中运行 npx -y [email protected] auth，并批准 WHOOP 访问权限。
4. 运行 npx -y [email protected] status，确认本地授权已存在。
5. 将 stdio 命令 npx -y [email protected] 添加到 AI 客户端的 MCP 配置中。
6. 重启或重新加载客户端，然后提问：Use WHOOP to summarize my recovery and sleep from the last 7 days.

授权命令和 AI 客户端必须由同一操作系统用户运行，或者两者都将 WHOOP_CREDENTIALS_FILE 设置为同一个私有文件。此软件包绝不会要求你将 WHOOP 令牌粘贴到 AI 对话中。

文档默认固定使用经过审查的确切版本。仅当你明确希望客户端在未经事先审查的情况下跟进未来版本时，才使用 @latest。

1. 创建 WHOOP 应用

在 WHOOP Developer Dashboard 中创建应用，并注册以下确切的重定向 URL：

http://127.0.0.1:8765/callback

启用以下权限范围：

offline
read:recovery
read:cycles
read:sleep
read:workout
read:body_measurement

WHOOP 访问令牌会过期，且 WHOOP 会轮换刷新令牌，因此必须启用 offline。

2. 在本地授权

运行：

npx -y [email protected] auth

此命令会提示你输入 WHOOP 客户端 ID，并隐藏客户端密钥；随后在浏览器中打开 WHOOP 授权页面、验证 OAuth 状态，并在本地保存授权结果。

凭据存储于：

~/.config/mcp-server-whoop/credentials.json

在 Linux 和 macOS 上，使用前会检查路径中的每个上级目录；直接父目录必须归当前用户所有且权限为 0700，凭据文件必须是归当前用户所有、仅有一个硬链接且权限为 0600 的常规文件。仅当 WHOOP_CREDENTIALS_FILE 路径的所有上级目录均可信且不是符号链接时，才可用它覆盖默认路径。

原生 Windows 上会有意拒绝使用持久化 OAuth 凭据。Node.js 文件模式无法强制执行 Windows 私有 ACL，而其标准文件 API 也无法保证写入凭据时安全处理重解析点。原生 Windows 用户可以通过 MCP 进程环境提供短时有效的 WHOOP_ACCESS_TOKEN，但在原生凭据后端可用之前，自动授权和刷新令牌持久化需要使用 WSL、Linux 或 macOS。

对于无头环境，请在运行 auth 前通过环境变量提供 WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET，并可选提供 WHOOP_REDIRECT_URI。

OAuth 回调仍需到达运行 auth 的机器。通过 SSH 授权时，请先从工作站创建一个回环隧道：

ssh -L 8765:127.0.0.1:8765 user@your-server

然后在该 SSH 会话中运行 auth，并在工作站浏览器中打开命令打印的 WHOOP URL。请勿将客户端密钥作为命令行参数传递，因为它可能会暴露在 shell 历史记录和进程列表中。

在不显示密钥的情况下检查设置：

npx -y [email protected] status

移除本地授权：

npx -y [email protected] logout

不再使用某项集成时，也建议在 WHOOP 账户设置中撤销访问权限。

3. 将其添加到 AI 客户端

Claude Desktop

将以下内容添加到 Claude Desktop 配置中的 mcpServers 下，然后完全重启 Claude Desktop：

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Claude Code

claude mcp add --transport stdio whoop -- npx -y [email protected]

Cursor、Windsurf、Gemini Code Assist 和其他 mcpServers 客户端

将该服务添加到客户端的 MCP JSON 配置中。Gemini Code Assist 使用 ~/.gemini/settings.json；其他客户端使用各自的设置路径。

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

VS Code

为项目创建 .vscode/mcp.json，或使用 VS Code 的 MCP: Add Server 命令：

{
  "servers": {
    "whoop": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Codex

可以运行：

codex mcp add whoop -- npx -y [email protected]

也可以将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.whoop]
command = "npx"
args = ["-y", "[email protected]"]

ChatGPT

支持 stdio 的本地 Codex 和 ChatGPT 桌面客户端可以使用上述 Codex 配置。ChatGPT 网页版不会在你的电脑上启动命令；它需要单独设有安全保护的远程桥接或隧道，以及工作区插件。本仓库不会提供或运营公共健康数据中继服务。

客户端菜单和配置路径会随时间变化。如果客户端支持标准的本地 stdio MCP，可移植的配置值始终如下：

command: npx
arguments: -y [email protected]

确认连接

重启客户端后，确认它发现的工具恰好是以下 5 个：

whoop_latest_overview
whoop_recovery_history
whoop_sleep_history
whoop_cycle_strain_history
whoop_workout_history

实用提示词：

• 使用 WHOOP 查看今天的恢复情况、最近一次睡眠、当前负荷和最近一次锻炼。
• 比较过去 14 天的恢复情况、HRV 和静息心率。
• 显示过去 7 天的睡眠（包括小睡），并标记仍在处理的数据。
• 总结过去 30 天的锻炼负荷和心率区间。
• 将 WHOOP 数据作为今天训练的参考，但不要将其视为医疗建议。

模型会决定何时调用工具；如果你想获取实时数据而非一般性回答，请明确说 使用 WHOOP。

工具

工具	用途
whoop_latest_overview	当前指导概览，并在数据尚未就绪时采取保护措施
whoop_recovery_history	恢复、HRV、静息心率、SpO2 和皮肤温度趋势
whoop_sleep_history	主要睡眠和可选小睡、睡眠阶段、睡眠需求、质量和时间
whoop_cycle_strain_history	每日负荷、卡路里以及平均/最高心率
whoop_workout_history	运动项目、时长、负荷、心率、卡路里、距离和心率区间分钟数

所有工具均标记为只读、非破坏性且幂等。

为什么特意只提供五个工具？

对于健康数据 MCP，工具数量越多，能力范围也越大。此服务将身份验证置于 Agent 之外，只向模型提供所需的五项健康数据读取能力。

它特意不提供：

• WHOOP 写入、撤销、令牌管理或授权码工具
• 个人资料/电子邮件/姓名权限范围
• 原始记录、原始 ID、任意端点、SQL、文件或 shell 工具
• 托管式 OAuth 中继、遥测服务、健康数据缓存或数据库
• 最新睡眠仍在处理时的旧恢复数据回退

目标不是最大限度覆盖 WHOOP API，而是为关注恢复的 AI 设定切实可行的最小权限边界。

数据语义

WHOOP 会为睡眠、周期和训练记录返回绝对时间戳及 timezone_offset。此服务会应用每条记录自身的偏移量，并且只返回已经转换为本地时间的时间戳，例如：

2026-07-07 18:02:22 +04:00

它不会将机器当前的时区应用于历史记录。

WHOOP 会提供活动类型和训练运动项目，但其公共 API 不会说明训练是自动检测的还是手动开始的。此服务不会猜测。

当最新的主要睡眠仍处于 PENDING_SCORE 状态时，最新概览会返回：

{
  "status": {
    "state": "waiting_for_whoop",
    "current_recovery_available": false
  },
  "recovery": null
}

绝不会将较早的恢复数据呈现为当前数据。

环境变量

变量	用途
WHOOP_CLIENT_ID	WHOOP OAuth 客户端 ID
WHOOP_CLIENT_SECRET	WHOOP OAuth 客户端密钥
WHOOP_REDIRECT_URI	OAuth 回调，默认为 http://127.0.0.1:8765/callback
WHOOP_CREDENTIALS_FILE	覆盖本地凭据文件路径
WHOOP_ACCESS_TOKEN	可选的短期访问令牌覆盖值
WHOOP_REFRESH_TOKEN	可选的刷新令牌覆盖值
WHOOP_TOKEN_EXPIRES_AT	可选的 ISO 令牌过期时间覆盖值

WHOOP_CLIENT_ID、WHOOP_CLIENT_SECRET 和 WHOOP_REDIRECT_URI 中的客户端配置会覆盖文件中的值。令牌环境变量可用于引导无头设置，但刷新令牌轮换后，凭据文件中保存的新令牌优先。请勿直接在命令行参数中放入密钥，也不要将其提交到源代码管理中。

故障排除

Missing WHOOP ...

请以启动 AI 客户端的同一操作系统用户身份运行 npx -y [email protected] status。如果凭据位于其他位置，请在客户端的 MCP 环境中设置 WHOOP_CREDENTIALS_FILE。

WHOOP 报告重定向地址不匹配

Developer Dashboard 中的重定向地址必须与此软件包使用的值完全一致。默认值为 http://127.0.0.1:8765/callback，包括协议、主机、端口和路径。

浏览器未打开

复制终端中打印的授权 URL 并手动打开。回调监听器会在五分钟后过期；如有需要，请重新运行 auth。

端口 8765 已被占用

注册另一个环回 URL，例如 http://127.0.0.1:9876/callback，将 WHOOP_REDIRECT_URI 设置为该确切值，然后重新运行 auth。

恢复数据为 null

检查返回的 status.state。如果是 waiting_for_whoop 或 waiting_for_recovery，说明 WHOOP 尚未完成对最新睡眠的评分。此服务会有意拒绝将较早的恢复数据标记为当前数据；请在 WHOOP 完成处理后重试。

客户端未显示任何工具

在终端中运行 npx -y [email protected] --help，确认 Node.js 和 npm 可以启动此软件包，然后重启 AI 客户端并检查其 MCP 日志。请勿直接交互式运行服务来查看输出：stdio 专用于 MCP 协议消息。

开发

git clone [email protected]:Yadheedhya06/mcp-server-whoop.git
cd mcp-server-whoop
npm ci --ignore-scripts
npm run check

运行本地源代码服务：

npm run dev

构建并检查确切的 npm 制品：

npm pack --dry-run

隐私与安全

本项目发布证据，而非声称任何软件包都绝对安全。请参阅完整的安全策略和可复现的安全证据。

• 每位用户都拥有自己的 WHOOP 开发者应用和 OAuth 授权。
• 凭据保留在本地，绝不会通过 MCP 工具返回。
• 此软件包不提供 WHOOP 写入、通用网络、Shell、文件系统或原始 API 透传工具。
• 在受支持的 POSIX 存储上，凭据文件及其所有上级目录都会接受检查，以排除符号链接、不安全的所有权或权限、过大的输入及意外字段。令牌刷新轮换使用心跳租约，不依赖 PID，并采用独占临时文件、原子替换、写入后验证和磁盘同步。原生 Windows 持久化会以失败关闭方式处理。
• WHOOP 和 OAuth 响应均有大小限制，并经过结构验证；提供方响应正文绝不会复制到 MCP 错误中。
• 直接依赖项使用精确版本。运行时仅有两个直接依赖项，且没有软件包安装生命周期脚本。
• CI 在 Node 18、20、22 和 24 上运行完整测试套件，增加 macOS 和 Windows 平台安全任务，审计源代码和确切编译后的 npm 运行时，验证 npm registry 签名，并生成 CycloneDX SBOM。
• 独立工作流运行 CodeQL、Gitleaks、依赖项审查和 OpenSSF Scorecard。
• 发布工作流只打包一次，并通过 npm Trusted Publishing 和 Sigstore 来源证明发布该确切的 tarball。GitHub 会单独证明该 tarball 与其 CycloneDX SBOM 的对应关系；不会使用长期有效的 npm 令牌。

这些控制措施可以降低风险，但并不等同于付费渗透测试，也无法提供保证。相关限制已在 SECURITY-EVIDENCE.md 中明确说明。

许可证

MIT