WHOOP MCP Server (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
3. 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

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

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

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

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

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

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

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

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

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

Check the connection at any time:

npx -y @oryanomer/whoop-mcp status

Uninstall

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.