WHOOP Integration¶
Cadence connects to WHOOP via OAuth2 to pull recovery scores, strain, sleep, and workout data.
Setup¶
1. Create a WHOOP Developer App¶
- Go to the WHOOP Developer Portal
- Create a new application
- Set the redirect URI to your server's callback URL:
- Local development:
http://localhost:8000/auth/whoop/callback - Production:
https://your-domain.com/auth/whoop/callback
- Local development:
2. Configure Environment Variables¶
WHOOP_CLIENT_ID=your-client-id
WHOOP_CLIENT_SECRET=your-client-secret
WHOOP_REDIRECT_URI=http://localhost:8000/auth/whoop/callback
3. Authorize¶
Navigate to http://localhost:8000/auth/whoop or use the whoop_connect MCP tool. You'll be redirected to WHOOP to authorize, then back to your server.
Token Persistence
For ephemeral deployments (Railway free tier), export tokens after initial auth with the whoop_export_tokens tool and set WHOOP_ACCESS_TOKEN, WHOOP_REFRESH_TOKEN, and WHOOP_TOKEN_EXPIRES_AT in your environment.
Available Data¶
Recovery & HRV¶
| Data | Tool | Description |
|---|---|---|
| Recovery | whoop_get_recovery |
Recovery score (0-100), HRV (ms), resting HR, SpO2 |
| Recovery history | whoop_get_recovery_history |
Multi-day recovery for trend analysis |
Sleep¶
| Data | Tool | Description |
|---|---|---|
| Sleep | whoop_get_sleep |
Stages, efficiency, performance, consistency, sleep debt, latency |
| Sleep history | whoop_get_sleep_history |
Multi-day sleep data for trend detection |
Strain & Workouts¶
| Data | Tool | Description |
|---|---|---|
| Strain | whoop_get_strain |
Day strain (0-21), avg/max HR, calories |
| Strain history | whoop_get_strain_history |
Multi-day strain for load reviews |
| Workouts | whoop_get_workouts |
Activities with sport type, HR zones, duration |
Analytics¶
| Data | Tool | Description |
|---|---|---|
| Training load | whoop_analyze_training_load |
Acute:Chronic Workload Ratio (ACWR) from strain history |
| Data export | whoop_export_data |
Export sleep/recovery/strain as CSV or JSON |
WHOOP-Specific Concepts¶
- Recovery Score (0-100): Combines HRV, resting HR, respiratory rate, and sleep performance. Green (67-100), Yellow (34-66), Red (0-33).
- Strain (0-21): Cardiovascular load accumulated throughout the day. Higher strain = more recovery needed.
- Sleep Performance: Percentage of sleep need actually achieved. WHOOP calculates your personal sleep need based on strain and baseline.
- ACWR: Acute:Chronic Workload Ratio. Cadence computes this from strain history. Optimal range is 0.8-1.3; above 1.5 is injury danger zone.