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 分