WHOOP MCP Server

A local Model Context Protocol (MCP) 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."

Related MCP server: Whoop MCP Server

Available Tools

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/ 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:

cd whoop-mcp
cp .env.example .env

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

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:

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:

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):

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:

{
  "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:

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.