# Whoop MCP Server

MCP server that exposes your Whoop fitness data (recovery, sleep, strain, workouts) to Claude for use as a daily training coach.

## Prerequisites

- Python 3.10+
- A [Whoop Developer](https://developer.whoop.com) account with a registered application
- Your Whoop app's Client ID and Client Secret

## Whoop Developer Dashboard Setup

1. Go to [developer.whoop.com](https://developer.whoop.com) and sign in
2. Create a new application
3. Set the **Redirect URI** to: `http://localhost:8080/callback`
4. Enable these scopes: `read:recovery`, `read:cycles`, `read:sleep`, `read:profile`, `read:body_measurement`
   - Note: `read:workout` and `offline` may not be available on all developer apps. The server handles missing scopes gracefully.
5. Note your **Client ID** and **Client Secret**

## Installation

```bash
cd whoop-mcp
pip install -r requirements.txt
```

## Authorization (One-Time Setup)

Export your app credentials and run the setup script:

```bash
export WHOOP_CLIENT_ID="your-client-id"
export WHOOP_CLIENT_SECRET="your-client-secret"
python scripts/setup_auth.py
```

This opens a browser to Whoop's authorization page. After you approve, tokens are encrypted and stored at `~/.whoop_mcp/`. If the `offline` scope was granted, tokens refresh automatically. Otherwise, re-run this script when the token expires.

## Claude Desktop / Cowork MCP Config

Add this to your Claude MCP configuration:

```json
{
  "mcpServers": {
    "whoop": {
      "command": "python",
      "args": ["/absolute/path/to/whoop-mcp/src/whoop_server.py"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Replace `/absolute/path/to/whoop-mcp` with the actual path on your machine.

## Available Tools

| Tool | Description |
|------|-------------|
| `whoop_check_auth` | Verify tokens are valid and not expired |
| `whoop_get_latest_recovery` | Most recent recovery score, HRV, resting HR, SpO2 |
| `whoop_get_recovery_range` | Recovery data for a date range |
| `whoop_get_latest_sleep` | Last sleep session with stage breakdown |
| `whoop_get_sleep_range` | Sleep data for a date range |
| `whoop_get_latest_strain` | Current cycle strain, avg/max HR, kilojoules |
| `whoop_get_strain_range` | Strain over past N days with average |
| `whoop_get_workouts` | Workouts with sport ID, strain, HR zones |
| `whoop_get_profile` | User profile and body measurements |
| `whoop_get_training_summary` | Aggregated coaching snapshot (start here) |

## Example Prompts

Once connected, you can ask Claude things like:

- "What was my recovery yesterday?"
- "How much strain did I accumulate last week?"
- "Am I trending toward overtraining?"
- "How has my HRV changed over the past two weeks?"
- "What were my sleep stages last night?"
- "Compare my strain to my recovery over the past 7 days."
- "Should I do a hard workout today?"

## Training Coach Workflow

Start each session by calling `whoop_get_training_summary` for an overview of recovery status, recent strain load, sleep quality, and a training readiness assessment.

## Token Storage

Tokens are stored encrypted at `~/.whoop_mcp/`:
- `.encryption_key` — Fernet encryption key (chmod 600)
- `tokens.enc` — Encrypted OAuth tokens (chmod 600)
- Directory permissions: chmod 700

If token refresh fails, re-run `python scripts/setup_auth.py`.