WHOOP MCP

Talk to Claude about your WHOOP data.

"How did I sleep this week?" "Is today a good day for a hard run?" "Show me my HRV trend and tell me if I'm overreaching."

This is a small, local MCP server that connects Claude (or any MCP client) to the official WHOOP Developer API v2 — recovery, sleep, strain, workouts, and body measurements.

It runs entirely on your own computer. Your data goes from WHOOP to your machine to Claude, and nowhere else. No server, no account, no telemetry.

---

Install (5 minutes, no coding)

Step 1 — Create your free WHOOP developer app

WHOOP requires everyone to use their own app credentials. It's free and takes about two minutes.

1. Go to https://developer-dashboard.whoop.com and sign in with your normal WHOOP account.

2. Click Create app. Name it anything (e.g. My Claude).

3. In Redirect URIs, enter exactly:

   http://localhost:8765/callback
   

   This is the single most common thing people get wrong. It must match character for character — no trailing slash, no https.

4. Tick these scopes:

   read:recovery · read:cycles · read:sleep · read:workout · read:profile · read:body_measurement · offline

5. Save, then copy the Client ID and Client Secret. Keep the tab open.

Step 2 — Download this project

Click the green Code button at the top of this page → Download ZIP, then unzip it somewhere you'll remember (e.g. your Documents folder).

Step 3 — Run the installer

Windows — open the unzipped folder and double-click install-windows.bat

macOS / Linux — open Terminal, then:

cd path/to/whoop-mcp
bash install.sh

The installer will:

1. find (or offer to install) Python 3.10+
2. install the two dependencies
3. ask you to paste your Client ID and Client Secret
4. open your browser so you can approve WHOOP access
5. write the Claude Desktop config for you — no JSON editing

Step 4 — Restart Claude

Fully quit Claude Desktop (not just close the window) and reopen it. Ask:

"What's my WHOOP recovery today?"

That's it.

---

What Claude can see

Tool	What it returns
whoop_readiness	Today's snapshot: recovery, HRV, RHR and sleep vs. your rolling baseline, recent strain load, plus personalised Karvonen HR training zones. Start here.
whoop_recovery	Daily recovery %, HRV (RMSSD), resting HR, SpO2, skin temperature
whoop_sleep	Sleep duration, performance %, efficiency %, consistency %, REM / deep / light / awake, disturbances, respiratory rate, sleep debt
whoop_cycles	Daily Strain (0–21), average and max HR, calories
whoop_workouts	Per-workout sport, duration, Strain, HR, distance, time in each of the 6 HR zones
whoop_body_measurements	Height, weight, WHOOP-measured max HR
whoop_profile	Name, email, user id — handy to confirm you're connected to the right account

All tools are read-only. Nothing can modify or delete your WHOOP data.

The HR zones in whoop_readiness are derived from your numbers — resting HR from your rolling recovery baseline, max HR from WHOOP's own measurement. You can override either (see Advanced below).

---

Things to try

Summarise my last 7 days of sleep and tell me what's hurting my recovery.
Compare my HRV this week against my 30-day baseline.
Based on my WHOOP readiness, what should today's run look like?
Which workouts last month had the highest strain per minute?
Plot my resting heart rate trend and flag anything unusual.
Am I showing signs of overreaching? Look at HRV, RHR and strain together.

---

Privacy & security

• Everything is local. The server runs on your machine as a subprocess of Claude. The only network calls it makes are to api.prod.whoop.com.
• Credentials never touch the Claude config. Your client ID, secret and OAuth tokens are stored in ~/.whoop-mcp/ with owner-only file permissions (0600 on macOS/Linux). The Claude config just points at the script.
• Read-only scopes. The server only ever issues GET requests.
• No telemetry, no analytics, no third-party services. Read whoop_mcp_server.py — it's one file, ~600 lines, no obfuscation.
• Access tokens are refreshed automatically. To cut access off entirely, delete ~/.whoop-mcp/ and revoke the app in your WHOOP developer dashboard.

Found a security issue? Please open an issue (or email the maintainer for anything sensitive) rather than filing a public PR.

---

Troubleshooting

"Token exchange failed" during setup Your redirect URI doesn't match. It must be exactly http://localhost:8765/callback in the WHOOP developer dashboard.

Claude doesn't show any WHOOP tools Fully quit Claude (Windows: right-click the tray icon → Quit; macOS: ⌘Q) and reopen. Then run the built-in check:

python whoop_mcp_server.py doctor

It prints exactly which piece is missing.

"Port 8765 is already in use" Set a different port, and add the matching redirect URI in the WHOOP dashboard:

WHOOP_REDIRECT_PORT=8799 python whoop_mcp_server.py auth

Windows: "python is not recognized" / wrong Python version Install Python 3.10+ from python.org and tick "Add python.exe to PATH", then run the installer again. Anaconda's Python is often too old and shadows the real one — the installer tries to work around this automatically.

Recovery or readiness comes back empty WHOOP needs a few days of wear to calibrate, and recovery only appears after a scored sleep. Check whoop_recovery for "calibrating": true.

Everything broke after a while Re-authorize: python whoop_mcp_server.py auth

---

Advanced

Manual Claude Desktop config

The installer does this for you, but if you'd rather do it by hand, add this to claude_desktop_config.json:

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

{
  "mcpServers": {
    "whoop": {
      "command": "python",
      "args": ["/full/path/to/whoop_mcp_server.py"]
    }
  }
}

Use the full absolute path to your Python executable if python isn't on PATH.

Use with Claude Code

claude mcp add whoop -- python /full/path/to/whoop_mcp_server.py

Environment variable overrides

Variable	Purpose
WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET	Supply credentials instead of using ~/.whoop-mcp/config.json
WHOOP_MCP_HOME	Where config and tokens live (default ~/.whoop-mcp)
WHOOP_REDIRECT_PORT	OAuth callback port (default 8765)
WHOOP_RHR	Force a resting-HR value for zone maths
WHOOP_MAX_HR	Force a max-HR value for zone maths

Commands

python whoop_mcp_server.py setup     # full guided setup
python whoop_mcp_server.py auth      # re-run OAuth only
python whoop_mcp_server.py doctor    # diagnose the install
python whoop_mcp_server.py           # run the MCP server (Claude does this)

---

Requirements

• Python 3.10+
• An active WHOOP membership
• Claude Desktop, Claude Code, or any MCP-compatible client

Contributing

Issues and pull requests welcome. Please don't include real WHOOP data, screenshots with personal metrics, or credentials in any issue.

License

MIT — see LICENSE.

Not affiliated with, endorsed by, or sponsored by WHOOP. "WHOOP" is a trademark of WHOOP, Inc. This project uses the publicly documented WHOOP Developer API. Nothing here is medical advice.