WHOOP (read-only)

io.github.oryanomer1由 GitHub 账号 oryanomer1 发布v1.0.3更新于 Oct 24, 2026

Read-only access to your WHOOP recovery, HRV, sleep, strain, workouts and trends.

已验证STDIO仅桌面位置与生活数据与分析

概览

AI 生成的概览

只读的 MCP 服务器，让助手查询你的 WHOOP 恢复、HRV、睡眠、负荷和训练数据。

可以做什么
一次调用汇总某天的恢复、睡眠、小睡、负荷、卡路里和训练，或生成最多 90 天的逐日趋势表，含恢复、HRV、静息心率、负荷和睡眠的平均值与范围。读取个人资料，如姓名、邮箱、身高、体重和最大心率。列出并获取生理周期，含负荷、卡路里、心率和步数。列出恢复记录，含恢复百分比、HRV、静息心率、血氧和皮肤温度。列出并获取睡眠记录，含表现、效率、阶段、干扰和呼吸频率；以及训练记录，含运动类型、时长、负荷、心率区间和距离，可按运动类型筛选。
适用场景
适合让助手回答关于你自己 WHOOP 历史数据的问题，例如昨晚睡得如何、今天恢复为何偏低，或高负荷日之后恢复是否变差，同时不授予对 WHOOP 账户的任何写入权限。
运行要求
通过 npx 以 stdio 在本地运行，需要 Node.js 20.11 或更高版本，以及 WHOOP 会员。需自行创建 WHOOP 开发者应用，勾选全部 read 权限并配置匹配的重定向 URI，然后运行一次 auth 命令；客户端 ID 和密钥可通过 WHOOP_CLIENT_ID 和 WHOOP_CLIENT_SECRET 提供，令牌保存在本地令牌文件中，路径可用 WHOOP_TOKEN_PATH 设置。需要能访问 WHOOP 的 API。
安装前请注意
客户端密钥和 OAuth 令牌保存在仅本人可读的本地令牌文件中，请妥善保管，并在每台机器上分别运行 auth，而不要复制令牌。工具结果（含健康数据）会由你的 MCP 客户端发送给其语言模型提供商，并受该提供商条款约束。服务器为只读，仅申请 read 权限，但可通过登出或在 WHOOP 后台删除应用来撤销访问。该项目为非官方项目，不构成医疗建议。

安装

在 SourceWeft 中

  1. 打开 控制台中的 WHOOP (read-only)，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

WHOOP MCP Server (read-only)

[npm] [CI] [M8ven Score] [whoop-mcp MCP server – quality and maintenance score on Glama] [License: MIT]

Ask Claude, Cursor, VS Code or any MCP client about your WHOOP recovery, HRV, sleep, strain and workouts, without giving it any way to change your data.

[Claude answering 'Why is my recovery low today?' with whoop-mcp: it calls get_daily_overview, notes the recovery is actually 76% (green), and explains the short sleep, low consistency and REM against solid HRV and resting heart rate.]

A real answer from real WHOOP data, recorded with npm run demo.

"How did I sleep last night, and why is my recovery only 41% today?" "Compare my HRV and resting heart rate over the last 30 days." "How many runs did I do this month, and what was my average strain?" "Do I recover worse after days with strain above 15?"

[Install in Cursor] [Install in VS Code]

(Run the one-time auth step before or after installing.)

Why this server

  • Read-only, enforced. It requests only WHOOP's read:* scopes. The HTTP client can only send GET, a test fails the build otherwise, and every tool carries readOnlyHint: true.
  • Answers whole questions in one call. get_daily_overview returns a day's recovery, sleep, naps, strain and workouts together. get_trends returns averages, ranges and recovery zones over up to 90 days.
  • Model-friendly output. It returns compact JSON with hours, km, kcal and local times instead of milliseconds and kilojoules, which saves tokens and avoids conversion mistakes. Pass raw: true for WHOOP's original objects.
  • Your tokens stay on your machine. Your own WHOOP developer app, a 0600 token file, and safe handling of WHOOP's rotating refresh tokens. No third-party servers.
  • Current API. It's built on the WHOOP Developer API v2.
  • Tested. Unit, MCP integration, end-to-end and packaging tests run on Linux, macOS and Windows with Node 20, 22 and 24.

Quick start

You need Node.js 20.11+ and a WHOOP membership.

1. Create a WHOOP developer app (2 minutes)

  1. Open the WHOOP Developer Dashboard and create a team if prompted.
  2. Create an app:
    • Scopes: select all the read:* scopes (recovery, cycles, workout, sleep, profile, body measurement).
    • Redirect URI: http://localhost:8787/callback
  3. Copy the Client ID and Client Secret.

2. Connect your WHOOP account

bash
npx -y @oryanomer/whoop-mcp auth

Paste your Client ID and Client Secret when asked. The secret isn't echoed, so it stays out of your screen and shell history. Your browser then opens WHOOP's consent page. When you approve, the tokens are saved to ~/.config/whoop-mcp/tokens.json and refreshed automatically from then on.

(For scripts, you can set WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET in the environment instead of answering the prompts.)

By connecting, you agree to the Terms of Use (EULA) and to WHOOP's API Terms of Use. See the Privacy Policy for how your data is handled.

3. Add it to your MCP client

Claude Code

As a plugin (recommended). Adds the server plus a /whoop:auth skill that walks you through connecting:

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

Or just the MCP server:

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

Use one or the other, not both, or you'll see every tool twice.

Claude Desktop

One click: download whoop-mcp-<version>.mcpb from the latest release and double-click it (or drag it onto Claude Desktop's Settings → Extensions page).

Or by hand: open Settings → Developer → Edit Config, and add:

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

Restart Claude Desktop. On Windows, if the server doesn't start, use "command": "cmd" and "args": ["/c", "npx", "-y", "@oryanomer/whoop-mcp"].

Cursor

Click the Install in Cursor button above, or add this to ~/.cursor/mcp.json:

json
{  "mcpServers": {    "whoop": {      "command": "npx",      "args": ["-y", "@oryanomer/whoop-mcp"]    }  }}
VS Code (GitHub Copilot)

Click the Install in VS Code button above, or add this to .vscode/mcp.json (or your user mcp.json):

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

Add this to ~/.codeium/windsurf/mcp_config.json:

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

Add this to ~/.codex/config.toml:

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

Run auth on the host first (step 2), then mount the token directory:

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

Use the docker run command as the stdio command in your MCP client.

Any other MCP client

Run npx -y @oryanomer/whoop-mcp as a stdio server. No environment variables are needed: the client ID and secret are stored with your tokens during auth.

Then ask: "Give me my WHOOP overview for today."

Tools

ToolWhat it returns
get_daily_overviewOne day's recovery, sleep, naps, strain, calories and workouts (defaults to today)
get_trendsDay-by-day table plus avg/min/max for recovery, HRV, resting HR, strain, sleep and more, over 1–90 days
get_profileName, email, height, weight, max heart rate
list_cycles / get_cyclePhysiological days: strain, calories, average/max heart rate, steps
list_recoveriesRecovery %, HRV (RMSSD), resting heart rate, SpO2, skin temperature
list_sleeps / get_sleepSleep performance, efficiency, consistency, stages, disturbances, respiratory rate, sleep need
list_workouts / get_workoutSport, duration, strain, heart rate, calories, distance, time in heart-rate zones (filterable by sport)

List tools accept start / end (YYYY-MM-DD or ISO date-time), a days shortcut, limit (up to 200, with automatic pagination) and next_token. See the tool reference for every parameter and example outputs.

Configuration

VariableDefaultPurpose
WHOOP_CLIENT_IDfrom token fileYour app's client ID (auth asks if unset)
WHOOP_CLIENT_SECRETfrom token fileYour app's client secret (auth asks, without echoing, if unset)
WHOOP_REDIRECT_URIhttp://localhost:8787/callbackMust exactly match a redirect URI registered on your app
WHOOP_TOKEN_PATH~/.config/whoop-mcp/tokens.jsonWhere credentials are stored. Must be absolute (~/ is expanded). Honours XDG_CONFIG_HOME.
text
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 connectionwhoop-mcp logout     Delete the locally stored tokenswhoop-mcp --version

All commands run via npx -y @oryanomer/whoop-mcp <command>, or install globally with npm install -g @oryanomer/whoop-mcp.

Privacy and security

Read the full Privacy Policy. In short:

  • whoop-mcp talks only to api.prod.whoop.com. There is no telemetry and no intermediary server.
  • Tokens and your client secret live in one file that only your user can read (0600). They are never logged or returned by tools.
  • Your MCP client sends tool results to its language model. Health data you ask about is shared with that model provider under its terms, so use a client and provider you trust.
  • To disconnect, run whoop-mcp logout to delete the local tokens. To revoke access completely, delete the app or rotate its secret in the WHOOP Developer Dashboard.

The full threat model is in SECURITY.md. Please report vulnerabilities privately through GitHub security advisories.

How authentication works

  • WHOOP access tokens last one hour. whoop-mcp refreshes them about a minute before they expire, and again if WHOOP returns a 401.
  • WHOOP issues a new refresh token on every refresh and rejects concurrent refreshes. whoop-mcp refreshes one request at a time, takes a lock file so several clients on one machine (e.g. Claude Desktop and Claude Code) never refresh at once, and writes new tokens atomically. If a write fails, the new tokens stay in memory, so a full disk can't log you out.
  • Rate limits (429), WHOOP server errors, timeouts (30s per request) and network errors are retried with backoff, honouring Retry-After. Cancelling a request in your client stops its WHOOP calls.

Troubleshooting

SymptomFix
WHOOP's sign-in page shows 400 Bad Request: Request Header Or Cookie Too LargeYour browser has too many whoop.com cookies. Copy the link that auth prints into a private/incognito window, or clear cookies for whoop.com, then try again.
WHOOP shows an error about the redirect URIThe redirect URI on your WHOOP app must match WHOOP_REDIRECT_URI exactly, including http://, the port and /callback, with no trailing slash or spaces.
Port 8787 is in useRegister another URI on your app (e.g. http://localhost:9876/callback) and run auth with WHOOP_REDIRECT_URI set to it.
Tool error Not connected to WHOOPRun the auth step. If your client runs as a different user or with a different HOME, set WHOOP_TOKEN_PATH in the client config to your token file.
Tool error WHOOP rejected the refresh tokenRun auth again. This happens if the app's secret was rotated, access was revoked, or the token file was copied to another machine and used there. Run auth on each machine instead of copying tokens.
Tool error 403 ... missing a scopeEnable all read:* scopes on your WHOOP app, then run auth again.
Values missing, score_state: PENDING_SCOREWHOOP hasn't finished scoring that sleep, recovery or workout. Ask again later.
The server doesn't appear in the clientRun npx -y @oryanomer/whoop-mcp --version in a terminal to check Node and npx, then restart the client. The first start downloads the package and can take a few seconds.

Check the connection at any time:

bash
npx -y @oryanomer/whoop-mcp status

Uninstall

bash
npx -y @oryanomer/whoop-mcp logout

Then remove the whoop entry from your MCP client's config, and delete the app in the WHOOP Developer Dashboard if you no longer need it.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. The one hard rule: whoop-mcp stays read-only. Release notes are in CHANGELOG.md.

Legal

  • License: MIT © Oryan Omer
  • Terms of use (EULA): EULA.md. By installing or using whoop-mcp you agree to these terms.
  • Privacy policy: PRIVACY.md
  • Security policy: SECURITY.md

This is an unofficial project, not affiliated with or endorsed by WHOOP, Inc. "WHOOP" is a trademark of WHOOP, Inc. Nothing here is medical advice.

来源：README.md，提交 cc7983c

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v1.0.3最新Oct 17, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分