WHOOP MCP Server

An MCP (Model Context Protocol) server that lets Claude query your personal WHOOP health data — recovery, sleep, strain, workouts, and profile — via WHOOP's official OAuth 2.0 REST API (v2).

Each person who uses this runs their own copy against their own WHOOP account: you register your own free developer app with WHOOP, and your tokens/credentials stay in local files on your machine (gitignored, and written with restrictive permissions) — they're never sent anywhere except directly between your machine and WHOOP's API.

That said, the health data these tools return is a different story: once a tool call happens, its result is returned to whatever MCP client/model you're using (e.g. Claude), so it's subject to that service's own privacy and data-handling policies from that point on. Only the credentials and tokens are guaranteed to stay local — the recovery scores, sleep data, etc. you ask about necessarily become visible to the model answering your question.

git clone https://github.com/vaibhavgoel63-arch/Whoop-MCP.git
cd Whoop-MCP

1. Get WHOOP API credentials

1. Go to the WHOOP Developer Dashboard and sign in.
2. Create (or open) an app.
3. Under the app's API settings, set the Redirect URI to exactly:

   http://localhost:8080/callback
   

4. Copy the Client ID and Client Secret — you'll paste these into .env in step 3 below.

2. Prerequisites

• Node.js 18+ (needed for the built-in fetch API). Check with node --version.

3. Install and configure

npm install
cp .env.example .env

Open .env and paste in your Client ID and Client Secret from step 1:

WHOOP_CLIENT_ID=your-client-id-here
WHOOP_CLIENT_SECRET=your-client-secret-here
WHOOP_REDIRECT_URI=http://localhost:8080/callback

⚠️ You must manually fill in WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET — the server will refuse to start any OAuth flow until these are set.

4. Build and log in (one-time)

npm run build
npm run login

This will:

1. Start a temporary local server on http://localhost:8080.
2. Open your browser to WHOOP's consent screen (requesting recovery, sleep, cycle, workout, profile, body-measurement, and offline/refresh scopes).
3. After you approve, WHOOP redirects back to localhost:8080/callback with an authorization code.
4. The script exchanges that code for an access + refresh token and saves them to token.json (gitignored) in the project root.

You only need to do this once. The MCP server automatically refreshes the access token using the refresh token when it expires (WHOOP access tokens last about 1 hour). If your refresh token is ever revoked or expires, just re-run npm run login.

5. Connect to Claude Desktop

Open your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Note: if you installed Claude Desktop from the Microsoft Store, the file above may just be a stub — the app actually reads %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json. If tools don't show up after following the steps below, check there.

Add a whoop entry under mcpServers. Replace the path below with the absolute path to this project's dist/server.js on your machine (find it with pwd on macOS/Linux or cd on Windows from inside the project folder):

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/server.js"]
    }
  }
}

⚠️ You must manually fill in this absolute path to wherever you cloned this repo. Use forward slashes even on Windows (e.g. C:/Users/you/whoop-mcp/dist/server.js) — they work fine inside this JSON file.

Then fully restart Claude Desktop (quit from the system tray, not just close the window).

6. Test it

1. In Claude Desktop, click the tools/hammer icon in the chat box and confirm you see whoop with 6 tools listed: get_recovery, get_sleep, get_strain, get_workouts, get_profile, get_training_recommendation.
2. Try these prompts:
   • "How was my recovery this week?"
   • "Should I train hard today?"
   • "How did I sleep the last 3 nights?"
   • "Show me my workouts from the last 7 days."
   • "What's my current strain and how does it compare to yesterday?"
   • "What was my average strain in March 2026?" (historical range, not just "last N days")
3. Spot-check one result (e.g. today's recovery score) against the WHOOP app to confirm the numbers match.

Tools reference

Tool	Description
get_recovery(days | start+end)	Recovery score, HRV, resting heart rate, SpO2, skin temp — plus an averages summary
get_sleep(days | start+end)	Sleep performance %, efficiency %, stage breakdown (light/deep/REM), and sleep_onset (full ISO timestamp of when sleep began, not just the date) — plus an averages summary
get_strain(days | start+end)	Daily strain, average/max heart rate, calories per day — plus an averages/totals summary
get_workouts(days | start+end)	Logged workouts with sport, duration, strain, heart rate, calories — plus a summary
get_profile()	Name, email, height, weight, max heart rate
get_training_recommendation()	Combines today's recovery + last 3 days of sleep into a green/yellow/red training recommendation, with a sleep-debt warning if performance has been under 80% for 2+ nights

The four range-based tools accept either days (rolling window, e.g. days=7 for the last week) or an explicit start/end date pair (YYYY-MM-DD, end exclusive) for querying a specific historical period, e.g. start="2026-03-01", end="2026-04-01" for all of March 2026. Each returns a summary object (averages/totals) alongside the individual daily/nightly records.

Troubleshooting

• "No WHOOP tokens found" — run npm run login.
• 401 / token errors after working before — the server auto-refreshes access tokens; if you see a refresh failure, your refresh token was likely revoked (e.g. you removed app access in WHOOP settings). Re-run npm run login.
• 403 Forbidden — your token is missing a scope. Scopes are fixed at login time, so re-run npm run login to get a fresh token with the full scope set.
• 429 Too Many Requests — you've hit WHOOP's rate limit (100 requests/minute, 10,000/day). Wait and try again.
• Tools don't show up in Claude Desktop — double-check the absolute path in claude_desktop_config.json, that you ran npm run build (the config points at dist/server.js, not src/server.ts), and that you fully restarted Claude Desktop.

Project structure

src/
  auth.ts        # OAuth constants, token load/save, refresh logic
  login.ts        # One-time login script (npm run login)
  whoopClient.ts  # Authenticated WHOOP API client + response normalizers
  server.ts       # MCP server exposing the 6 tools
.env.example      # Template for WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET / WHOOP_REDIRECT_URI

.env (credentials) and token.json (access/refresh tokens) are both gitignored — never commit either file.