WHOOP MCP

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 connectsClaude (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 machineto 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 takesabout two minutes.

1. Go to https://developer-dashboard.whoop.com and sign in with your normalWHOOP 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 matchcharacter 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, thenunzip 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

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 HRfrom your rolling recovery baseline, max HR from WHOOP's own measurement. You canoverride 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 ofClaude. The only network calls it makes are to api.prod.whoop.com.
• Credentials never touch the Claude config. Your client ID, secret andOAuth 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. Readwhoop_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 foranything sensitive) rather than filing a public PR.

Troubleshooting

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

Claude doesn't show any WHOOP toolsFully quit Claude (Windows: right-click the tray icon → Quit; macOS: ⌘Q) andreopen. 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 versionInstall Python 3.10+ from python.org andtick "Add python.exe to PATH", then run the installer again. Anaconda'sPython is often too old and shadows the real one — the installer tries to workaround this automatically.

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

Everything broke after a whileRe-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 toclaude_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

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 trademarkof WHOOP, Inc. This project uses the publicly documented WHOOP Developer API.Nothing here is medical advice.