# WHOOP MCP Server

A local [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects your WHOOP account directly to the Claude desktop app. Once set up, Claude can read your recovery scores, sleep data, strain, workouts, and more — all in real time, just by asking.

---

## How It Works

```
Claude Desktop App
       │
       │  (stdio — Claude launches the Python process automatically)
       ▼
  main.py  ──►  WHOOP API v2  ──►  Your health data
```

Claude manages the server process itself. You don't need to run anything manually — just configure it once, restart Claude, and start asking questions like *"How did I recover today?"* or *"Give me my strain data from last week."*

---

## Available Tools

| Tool | Description |
|------|-------------|
| `get_recovery` | Today's recovery score, HRV, resting HR, SpO2, skin temperature |
| `get_sleep` | Most recent sleep: duration, stages (light/REM/deep), efficiency, performance |
| `get_strain` | Today's day strain score, kJ burned, avg and max heart rate |
| `get_workouts` | Last 5 workouts: sport, duration, strain, HR zones |
| `get_profile` | Name, email, height, weight, max heart rate |
| `get_date_range_summary` | Full summary (recovery + sleep + strain + workouts) for any date range |

---

## Prerequisites

- **Python 3.11+**
- **A WHOOP account** with a WHOOP 4.0 or later device
- **Claude desktop app** (Cowork or standard)
- **A WHOOP Developer App** (free, takes ~2 minutes to set up)

---

## Setup

### Step 1 — Create a WHOOP Developer App

1. Go to [https://developer.whoop.com/](https://developer.whoop.com/) and sign in with your WHOOP account.
2. Click **Create App**.
3. Fill in any name (e.g. `Claude Integration`) and a short description.
4. Under **Redirect URIs**, add exactly:
   ```
   http://localhost:8000/callback
   ```
5. Under **Scopes**, select all of the following:
   - `read:recovery`
   - `read:cycles`
   - `read:sleep`
   - `read:workout`
   - `read:profile`
   - `read:body_measurement`
   - `offline`
6. Save the app. Copy your **Client ID** and **Client Secret** — you'll need them in the next step.

---

### Step 2 — Configure Your Credentials

Clone or download this repository, then navigate into it:

```bash
cd whoop-mcp
cp .env.example .env
```

Open `.env` and fill in your credentials from Step 1:

```env
WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
```

> **Security note:** `.env` and `tokens.json` are listed in `.gitignore` and will never be committed to version control.

---

### Step 3 — Install Dependencies

Create a virtual environment and install the required packages:

```bash
python3 -m venv .venv
source .venv/bin/activate        # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

---

### Step 4 — Authenticate with WHOOP (One-Time Only)

Run the authentication script. This opens your browser, walks you through WHOOP's OAuth flow, and saves your tokens locally:

```bash
python auth.py
```

What happens:
1. Your browser opens to the WHOOP authorization page.
2. You approve access for the requested scopes.
3. WHOOP redirects to `http://localhost:8000/callback`.
4. The script exchanges the authorization code for tokens and saves them to `tokens.json`.

You only need to do this once. The server automatically refreshes your access token when it expires.

---

### Step 5 — Add to Claude Desktop App

Claude uses a config file to know which MCP servers to launch. You need to add the WHOOP server to it.

**Find (or create) the config file:**

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

Run this command in Terminal to add the WHOOP server automatically (it safely merges into any existing config):

```bash
python3 -c "
import json
path = '/Users/YOUR_USERNAME/Library/Application Support/Claude/claude_desktop_config.json'
with open(path) as f:
    config = json.load(f)
config['mcpServers'] = config.get('mcpServers', {})
config['mcpServers']['whoop'] = {
    'command': '/Users/YOUR_USERNAME/whoop-mcp/.venv/bin/python',
    'args': ['/Users/YOUR_USERNAME/whoop-mcp/main.py'],
    'cwd': '/Users/YOUR_USERNAME/whoop-mcp'
}
with open(path, 'w') as f:
    json.dump(config, f, indent=2)
print('Done')
"
```

> Replace `YOUR_USERNAME` with your macOS username (e.g. `johndoe`). You can find it by running `whoami` in Terminal.

The result in your config file should look like this:

```json
{
  "mcpServers": {
    "whoop": {
      "command": "/Users/YOUR_USERNAME/whoop-mcp/.venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/whoop-mcp/main.py"],
      "cwd": "/Users/YOUR_USERNAME/whoop-mcp"
    }
  }
}
```

---

### Step 6 — Restart Claude

Fully quit the Claude desktop app (**Cmd+Q**, not just closing the window) and reopen it. Claude will automatically launch the WHOOP MCP server in the background when it starts up.

You're ready. Try asking Claude:

- *"What's my recovery today?"*
- *"How did I sleep last night?"*
- *"Give me my strain and workout data from June 10th to June 15th."*
- *"Analyze my last week of WHOOP data and tell me if I'm overtraining."*

---

## Using the Date Range Tool

The `get_date_range_summary` tool lets you pull a full week (or any range) of data in one shot. Just ask Claude naturally:

> *"Give me all my WHOOP data from June 9th to June 15th."*

Claude will return a breakdown of recovery, sleep, day strain, and workouts for every day in that range, formatted like this:

```
=== WHOOP Summary: 2026-06-09 to 2026-06-15 ===

── RECOVERY ──
  2026-06-09:  Score 72%  |  HRV 45.3ms  |  RHR 58bpm
  ...

── SLEEP ──
  2026-06-09:  7h 42m  |  Performance 84%  |  Efficiency 91%
  ...

── DAY STRAIN ──
  2026-06-09:  Strain 16.66/21  |  Avg HR 76bpm  |  Max HR 186bpm  |  12336 kJ
  ...

── WORKOUTS ──
  2026-06-10:  Running  |  45m 12s  |  Strain 14.20/21  |  Avg HR 158bpm
  ...
```

---

## Project Structure

```
whoop-mcp/
├── main.py           # MCP server — tool definitions and request handlers
├── whoop_client.py   # WHOOP API v2 client with token management
├── auth.py           # One-time OAuth 2.0 authentication flow
├── requirements.txt  # Python dependencies
├── .env.example      # Template for credentials
├── .env              # Your credentials (git-ignored)
└── tokens.json       # OAuth tokens (git-ignored, auto-refreshed)
```

---

## Troubleshooting

**"Missing environment variables" on startup**
→ Make sure `.env` exists in the project folder and contains both `WHOOP_CLIENT_ID` and `WHOOP_CLIENT_SECRET`.

**"No tokens.json found" on startup**
→ Run `python auth.py` first. You must complete the OAuth flow before the server can make API calls.

**"401 Unauthorized" from the WHOOP API**
→ Your tokens have expired or been revoked. Delete `tokens.json` and re-run `python auth.py` to get fresh tokens.

**WHOOP tools don't appear in Claude after restart**
→ Double-check the paths in `claude_desktop_config.json`. Both the `command` (Python path) and `cwd` must be absolute paths pointing to your actual install location. Run `which python3` inside your activated venv to confirm the Python path.

**Recovery or sleep data shows "No data for this period"**
→ WHOOP only generates recovery scores after a completed, scored sleep session. Make sure you're wearing your WHOOP overnight. Workouts only appear if activities are explicitly logged in the WHOOP app.

**Port 8000 already in use during auth**
→ Something else is using port 8000. Kill it first:
```bash
lsof -ti:8000 | xargs kill -9
```
Then re-run `python auth.py`.

---

## Security Notes

- `tokens.json` and `.env` are excluded from git via `.gitignore` — never commit them.
- The MCP server runs locally on your machine and communicates with Claude via stdio, not over the network.
- All WHOOP API calls are **read-only**. This server cannot modify your WHOOP data.
- Your WHOOP credentials are never sent to Claude or Anthropic — only the formatted health data responses are.

---

## Requirements

```
mcp[cli]>=1.2.0
httpx>=0.27.0
python-dotenv>=1.0.0
fastapi>=0.110.0
uvicorn>=0.29.0
```

---

## License

MIT License — see `LICENSE` for details.