A Model Context Protocol server for the Whoop API with OAuth 2.1 authentication. Modeled after the Fitbit and Oura MCPs in this monorepo.
Gives Claude access to your Whoop recovery, strain, sleep, and workout data via 11 read-only tools.
- Python 3.12
- MCP Python SDK (FastMCP)
- httpx
- Docker
- Docker and Docker Compose
- A Whoop developer app with a client ID and secret
- A publicly reachable HTTPS endpoint that forwards to this container on port 8000 (e.g. nginx + Let's Encrypt, ngrok, or Cloudflare Tunnel — your choice)
- Go to developer-dashboard.whoop.com and create an app.
- Set the Redirect URI to
https://<your-public-host>/whoop-callback(must matchSERVER_URLbelow exactly). - Enable these scopes:
offline(required to receive a refresh token)read:recoveryread:cyclesread:workoutread:sleepread:profileread:body_measurement
- Note your Client ID and Client Secret.
-
Clone the repo and
cdinto it. -
Copy the environment template:
cp .env.example .env
-
Fill in
.env:WHOOP_CLIENT_ID=your_client_id WHOOP_CLIENT_SECRET=your_client_secret SERVER_URL=https://your-public-host.example.com
-
Start the service:
docker compose up -d
The container listens on host port 8000. Put your own HTTPS reverse proxy in front so
https://<your-public-host>reaches it.
ngrok (quick test):
ngrok http 8000
# Use the https URL ngrok prints as your SERVER_URL.nginx reverse proxy (sketch):
server {
listen 443 ssl http2;
server_name your-public-host.example.com;
# ssl_certificate ...
# ssl_certificate_key ...
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}Connector URL:
https://<your-public-host>/mcp
OAuth runs automatically the first time you connect — you'll be redirected to Whoop to grant access.
claude_desktop_config.json:
{
"mcpServers": {
"whoop": {
"type": "http",
"url": "https://<your-public-host>/mcp"
}
}
}| Category | Tools |
|---|---|
| Cycle | get_cycle_collection, get_cycle_by_id, get_sleep_for_cycle |
| Recovery | get_recovery_collection, get_recovery_for_cycle |
| Sleep | get_sleep_collection, get_sleep_by_id |
| Workout | get_workout_collection, get_workout_by_id |
| User | get_profile_basic, get_body_measurement |
| Activity Mapping | get_activity_v2_id (v1 → v2 ID lookup) |
Collection tools accept limit (1-25), start, end (ISO-8601), and nextToken for pagination.
Whoop tokens are persisted to /data/.whoop_tokens.json inside the container (backed by the whoop-data Docker volume), so authorization survives restarts. Whoop rotates refresh tokens on every refresh — both fields are written back to disk after each refresh.
- All tools are read-only. The
DELETE /v2/user/accessendpoint is intentionally not exposed. - Webhooks are not implemented — Whoop's v1 webhooks were removed and v2 webhooks aren't part of this server.
- Single-user: like Oura and Fitbit, this server stores one user's tokens.