# 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](https://modelcontextprotocol.io) 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:

```bash
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](#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:

```bash
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:

```bash
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](https://www.python.org/downloads/) 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`

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

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

```bash
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](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.