WHOOP (read-only)

WHOOP MCP Server (read-only)

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.

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?"*

(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

1. Copy the Client ID and Client Secret.

2. Connect your WHOOP account

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:

/plugin marketplace add oryanomer1/whoop-mcp

/plugin install whoop@whoop-mcp

Or just the MCP server:

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- .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:

{

"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:

{

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

</details>

VS Code (GitHub Copilot)

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

{

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

</details>

Windsurf

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

{

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

</details>

OpenAI Codex CLI

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

[mcp_servers.whoop]

command = "npx" args = ["-y", "@oryanomer/whoop-mcp"]

</details>

Docker

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

docker build -t whoop-mcp https://github.com/oryanomer1/whoop-mcp.git

docker 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

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](docs/tools.md) for every parameter and example outputs.

Configuration

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 connection whoop-mcp logout Delete the locally stored tokens whoop-mcp --version

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

Privacy and security

Read the full [Privacy Policy](PRIVACY.md). 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

| V