whoop-mcp

A Model Context Protocol (MCP) server that connects your Whoop fitness data to Claude. Ask natural language questions about your recovery, sleep, workouts, and more — directly in Claude chat.

What You Can Ask

• "What was my recovery score today?"
• "How did I sleep this week?"
• "Show me my HRV trend over the last 30 days"
• "Which workouts had the highest strain?"
• "Compare my sleep efficiency this month"

Available Tools

Tool	Description
get_profile	Your name and email
get_body_measurement	Height, weight, max heart rate
get_recovery	Recovery %, HRV, resting heart rate, SpO2
get_sleep	Duration, efficiency, sleep stages, disturbances
get_workouts	Strain, calories, sport type
get_cycles	Daily strain and total calories burned

All data tools accept optional start and end date parameters and default to the last 30 days.

---

Setup

1. Prerequisites

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone this repo to a path without spaces:

git clone https://github.com/your-username/whoop-mcp.git ~/whoop-mcp
cd ~/whoop-mcp

Install dependencies:

uv venv --python 3.12
uv pip install mcp httpx

2. Get Whoop API credentials

1. Go to https://developer.whoop.com/
2. Create a new app and fill in:
   • Redirect URI: http://localhost:8888/callback
   • Privacy Policy URL: your GitHub Pages URL (see Privacy Policy below)
3. Copy your Client ID and Client Secret

3. Authenticate (one time only)

WHOOP_CLIENT_ID=your_client_id \
WHOOP_CLIENT_SECRET=your_client_secret \
.venv/bin/python auth.py

This opens the Whoop authorization page in your browser. After you approve:

• Your browser will show an error on localhost:8888 — that's expected
• Copy the full URL from the address bar and paste it into the terminal
• Tokens are saved to ~/.whoop_tokens.json

You will not need to do this again. The server automatically refreshes your token.

4. Configure the Claude Desktop App

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "whoop": {
      "command": "/Users/your-username/whoop-mcp/.venv/bin/python",
      "args": ["/Users/your-username/whoop-mcp/server.py"],
      "env": {
        "WHOOP_CLIENT_ID": "your_client_id",
        "WHOOP_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Important: The path to whoop-mcp must not contain spaces — this is why step 1 clones to ~/whoop-mcp.

5. Restart Claude

Fully quit Claude (Cmd+Q) and reopen it. The Whoop server should show as connected under Settings → Developer.

---

Privacy Policy

privacy.html is a ready-to-host privacy policy page required by the Whoop developer portal.

Host it on GitHub Pages:

1. Push this repo to GitHub
2. Go to Settings → Pages → Source → Deploy from a branch → main / root
3. Your privacy policy URL will be:

   https://your-username.github.io/whoop-mcp/privacy.html
   

---

Webhooks (optional)

webhook_server.py receives real-time events from Whoop when new data is recorded.

WHOOP_CLIENT_SECRET=your_client_secret .venv/bin/python webhook_server.py

For local development, expose it with ngrok:

ngrok http 8080
# Register the https URL in the Whoop developer portal

Supported events: workout.updated, sleep.updated, recovery.updated, body_measurement.updated

---

Project Structure

whoop-mcp/
├── server.py            # MCP server — tools Claude calls
├── whoop_client.py      # Whoop API v2 client with auto token refresh
├── auth.py              # One-time OAuth setup script
├── webhook_server.py    # Real-time Whoop event receiver (optional)
├── privacy.html         # Privacy policy page for GitHub Pages
└── requirements.txt     # Python dependencies (mcp, httpx)

Notes

• Tokens are stored at ~/.whoop_tokens.json and auto-refreshed — you never need to re-run auth.py unless you revoke access from the Whoop app
• Uses the Whoop API v2
• Tested on macOS with Python 3.12