WHOOP MCP 服务器

一个MCP（模型上下文协议）服务器，让Claude查询您的个人WHOOP健康数据—— 恢复、睡眠、压力、锻炼和个人资料——通过WHOOP的官方OAuth 2.0 REST API（v2）。

每个使用者都运行自己的副本，连接到自己的WHOOP账户：您需要向WHOOP注册自己的免费开发者应用， 您的令牌/凭据将保存在本地机器上的文件中（已git忽略）——除了您的机器和WHOOP的API之间， 不会共享或发送任何内容。

git clone https://github.com/vaibhavgoel63-arch/Whoop-MCP.git
cd Whoop-MCP

1. 获取WHOOP API凭据

1. 前往WHOOP开发者仪表盘并登录。

2. 创建（或打开）一个应用。

3. 在应用的API设置中，将重定向URI设置为完全：

   http://localhost:8080/callback

4. 复制客户端ID和客户端密钥——您将在下面的第3步中将其粘贴到.env中。

Related MCP server: Whoop MCP Server

2. 前提条件

• Node.js 18+（需要内置的fetch API）。通过node --version检查。

3. 安装和配置

npm install
cp .env.example .env

打开.env并粘贴您在第1步中获得的客户端ID和客户端密钥：

WHOOP_CLIENT_ID=your-client-id-here
WHOOP_CLIENT_SECRET=your-client-secret-here
WHOOP_REDIRECT_URI=http://localhost:8080/callback

⚠️ 您必须手动填写WHOOP_CLIENT_ID和WHOOP_CLIENT_SECRET——在设置这些之前，服务器将拒绝启动任何OAuth流程。

4. 构建并登录（一次性）

npm run build
npm run login

这将：

1. 在http://localhost:8080上启动一个临时本地服务器。

2. 在浏览器中打开WHOOP的同意屏幕（请求恢复、睡眠、周期、锻炼、个人资料、身体测量和离线/刷新范围）。

3. 您批准后，WHOOP会重定向回localhost:8080/callback，并附带一个授权码。

4. 脚本将该代码交换为访问令牌+刷新令牌，并将其保存到项目根目录的token.json中（已git忽略）。

您只需执行一次此操作。MCP服务器会在访问令牌过期时自动使用刷新令牌刷新（WHOOP访问令牌大约持续1小时）。如果您的刷新令牌被撤销或过期，只需重新运行npm run login。

5. 连接到Claude Desktop

打开您的Claude Desktop配置文件：

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

注意：如果您从Microsoft Store安装了Claude Desktop，上述文件可能只是一个存根——应用程序实际读取的是 %LOCALAPPDATA%\Packages\<Claude包文件夹>\LocalCache\Roaming\Claude\claude_desktop_config.json。 如果按照以下步骤操作后工具没有出现，请检查该位置。

在mcpServers下添加一个whoop条目。将下面的路径替换为您机器上此项目dist/server.js的绝对路径（在项目文件夹内使用macOS/Linux的pwd或Windows的cd命令找到它）：

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/server.js"]
    }
  }
}

⚠️ 您必须手动填写此绝对路径，指向您克隆此仓库的位置。即使在Windows上也要使用正斜杠（例如C:/Users/you/whoop-mcp/dist/server.js）——它们在JSON文件中可以正常工作。

然后完全重启Claude Desktop（从系统托盘退出，而不仅仅是关闭窗口）。

6. 测试

1. 在Claude Desktop中，点击聊天框中的工具/锤子图标，确认您看到whoop列出了6个工具：get_recovery、get_sleep、get_strain、get_workouts、get_profile、get_training_recommendation。

2. 尝试以下提示：

   • "我这周的恢复情况如何？"

   • "我今天应该高强度训练吗？"

   • "我过去3晚的睡眠如何？"

   • "显示我过去7天的锻炼记录。"

   • "我当前的压力是多少？与昨天相比如何？"

   • "2026年3月我的平均压力是多少？"（历史范围，不仅仅是最近N天）

3. 抽查一个结果（例如今天的恢复评分）与WHOOP应用进行对比，确认数字匹配。

工具参考

四个基于范围的工具接受days（滚动窗口，例如days=7表示最近一周）或明确的start/end日期对（YYYY-MM-DD，结束日期不包含），用于查询特定的历史时期，例如start="2026-03-01", end="2026-04-01"表示2026年整个3月。每个工具都返回一个summary对象（平均值/总和）以及各个每日/夜间records。

故障排除

• "未找到WHOOP令牌" — 运行npm run login。

• 之前正常工作后出现401/令牌错误 — 服务器会自动刷新访问令牌；如果您看到刷新失败，可能是您的刷新令牌被撤销了（例如您在WHOOP设置中删除了应用访问权限）。重新运行npm run login。

• 403禁止访问 — 您的令牌缺少某个范围。范围在登录时固定，因此重新运行npm run login以获取具有完整范围集的新令牌。

• 429请求过多 — 您已达到WHOOP的速率限制（每分钟100次请求，每天10,000次）。请稍后再试。

• 工具未在Claude Desktop中显示 — 请仔细检查claude_desktop_config.json中的绝对路径，确保您已运行npm run build（配置指向dist/server.js，而不是src/server.ts），并且您已完全重启Claude Desktop。

项目结构

src/
  auth.ts        # OAuth constants, token load/save, refresh logic
  login.ts        # One-time login script (npm run login)
  whoopClient.ts  # Authenticated WHOOP API client + response normalizers
  server.ts       # MCP server exposing the 6 tools
.env.example      # Template for WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET / WHOOP_REDIRECT_URI

.env（凭据）和token.json（访问/刷新令牌）都已git忽略——切勿提交这两个文件中的任何一个。