WHOOP (read-only)

io.github.oryanomer1Published by GitHub account oryanomer1v1.0.3Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Read-only MCP server that lets an assistant query your WHOOP recovery, HRV, sleep, strain and workout data.

What you can do
Summarize a day's recovery, sleep, naps, strain, calories and workouts in one call, or build day-by-day trend tables with averages and ranges over up to 90 days for recovery, HRV, resting heart rate, strain and sleep. Read profile details such as name, email, height, weight and max heart rate. List and fetch physiological cycles with strain, calories, heart rate and steps. List recoveries with recovery percentage, HRV, resting heart rate, SpO2 and skin temperature. List and fetch sleeps with performance, efficiency, stages, disturbances and respiratory rate, and workouts with sport, duration, strain, heart-rate zones and distance, filterable by sport.
When to use it
Useful when you want an assistant to answer questions about your own WHOOP history, such as last night's sleep, why recovery is low, or whether recovery drops after high-strain days, without granting any write access to your WHOOP account.
Requirements
Runs locally over stdio via npx, so Node.js 20.11 or newer is needed, plus a WHOOP membership. You must create your own WHOOP developer app with all read scopes and the matching redirect URI, then run the auth command once; the client ID and secret can be supplied through WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET, and tokens are stored in a local token file whose path can be set with WHOOP_TOKEN_PATH. Network access to WHOOP's API is required.
Before you install
The client secret and OAuth tokens are stored in a local token file readable only by your user; keep it private and run auth on each machine rather than copying tokens. Tool results, including health data, are sent by your MCP client to its language model provider under that provider's terms. The server is read-only and requests only read scopes, but you can revoke access by logging out or deleting the app in the WHOOP dashboard. It is unofficial and not medical advice.

Installation

In SourceWeft

  1. Open WHOOP (read-only) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: README.md at commit cc7983c

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.0.3LatestOct 17, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts