Whoop MCP Server

An MCP (Model Context Protocol) server that provides access to your Whoop health and fitness data, enabling Claude and other AI assistants to give you personalized health recommendations.

New here? Check out HOW_TO_USE.md for a step-by-step setup guide.

Features

• Recovery Data: Get your recovery score, HRV, resting heart rate, SpO2, and skin temperature
• Sleep Analysis: Detailed sleep stages (light, REM, deep), sleep performance, efficiency, and respiratory rate
• Workout Tracking: Strain scores, calories burned, heart rate zones, distance, and elevation
• Daily Strain: Cumulative daily strain and energy expenditure
• Health Overview: Combined view of recovery, sleep, and strain with personalized recommendations
• Profile & Body Measurements: User profile and body measurements data

Prerequisites

1. Whoop Device: You need an active Whoop membership
2. Whoop Developer Account: Create an app at developer.whoop.com
3. Node.js 18+: Required to run the server

Setup

1. Create a Whoop Developer App

1. Go to developer-dashboard.whoop.com
2. Create a new app
3. Set the redirect URL to http://localhost:8080/callback
4. Note your Client ID and Client Secret
5. Request the following scopes:
   • read:recovery
   • read:cycles
   • read:workout
   • read:sleep
   • read:profile
   • read:body_measurement
   • offline (for refresh token)

2. Install the MCP Server

cd whoop-mcp-server
npm install
npm run build

3. Get Your Initial Tokens (One-Time)

Run the token helper script:

node get-tokens.mjs

Follow the prompts to:

1. Enter your Client ID and Client Secret
2. Open the authorization URL in your browser
3. Authorize the app and copy the code from the redirect URL
4. The script will output your initial tokens

4. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/path/to/whoop-mcp-server/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret",
        "WHOOP_ACCESS_TOKEN": "your-initial-access-token",
        "WHOOP_REFRESH_TOKEN": "your-initial-refresh-token"
      }
    }
  }
}

5. First Use & Token Persistence

On first API call, the server will:

1. Use your initial tokens from the config
2. Save them to tokens.json in the server directory
3. Automatically refresh when they expire

After initial setup, you can remove WHOOP_ACCESS_TOKEN and WHOOP_REFRESH_TOKEN from your config. The server only needs:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/path/to/whoop-mcp-server/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Token Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         STARTUP                                 │
├─────────────────────────────────────────────────────────────────┤
│  Claude Desktop starts → WHOOP MCP server launches              │
│                              │                                  │
│                              ▼                                  │
│                   Check for tokens.json                         │
│                        /          \                             │
│                    Found          Not Found                     │
│                      │                │                         │
│                      ▼                ▼                         │
│              Use persisted      Use env vars                    │
│                tokens          (initial setup)                  │
│                      \              /                           │
│                       ▼            ▼                            │
│                    Token loaded in memory                       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                       ON API CALL                               │
├─────────────────────────────────────────────────────────────────┤
│  You ask "get my recovery" → check token expiry                 │
│                              │                                  │
│                     Token expired?                              │
│                        /          \                             │
│                      YES          NO                            │
│                       │            │                            │
│                       ▼            │                            │
│              Refresh via WHOOP     │                            │
│              API (uses client      │                            │
│              credentials +         │                            │
│              refresh token)        │                            │
│                       │            │                            │
│                       ▼            │                            │
│              Save new tokens       │                            │
│              to tokens.json        │                            │
│                       \           /                             │
│                        ▼         ▼                              │
│                   Make API call with valid token                │
└─────────────────────────────────────────────────────────────────┘

Key files:

• tokens.json - Persisted tokens (auto-created, survives restarts)
• dist/index.js - The MCP server

What's automatic:

• Token refresh when expired
• Saving new tokens to disk
• Loading tokens on restart

What requires manual action:

• Initial OAuth setup (one-time)
• Re-authentication if unused for 30-90 days (refresh token expires)

Available Tools

whoop_get_profile

Get your Whoop user profile (name, email, user ID).

whoop_get_body_measurements

Get your body measurements (height, weight, max heart rate).

whoop_get_recovery

Get recovery data including recovery score, HRV, resting heart rate, SpO2.

Parameters:

• limit (1-25, default 7): Number of records
• start: Start date filter (ISO 8601)
• end: End date filter (ISO 8601)

whoop_get_sleep

Get detailed sleep data including sleep stages, performance, and efficiency.

Parameters:

• limit (1-25, default 7): Number of records
• start: Start date filter (ISO 8601)
• end: End date filter (ISO 8601)

whoop_get_workouts

Get workout data including strain, calories, heart rate zones.

Parameters:

• limit (1-25, default 10): Number of records
• start: Start date filter (ISO 8601)
• end: End date filter (ISO 8601)

whoop_get_cycles

Get daily physiological cycle data (strain, calories, heart rate).

Parameters:

• limit (1-25, default 7): Number of records
• start: Start date filter (ISO 8601)
• end: End date filter (ISO 8601)

whoop_get_health_overview

Get a comprehensive health overview combining recovery, sleep, and strain data with personalized recommendations.

Example Usage with Claude

Once configured, you can ask Claude things like:

• "How's my recovery today?"
• "Show me my sleep from last week"
• "What workouts have I done recently?"
• "Give me a health overview"
• "Based on my Whoop data, should I train hard today?"
• "How has my HRV trended this week?"
• "What was my sleep quality like last night?"

Troubleshooting

"No tokens available" error

Run node get-tokens.mjs to get initial tokens, or check that tokens.json exists.

"Missing WHOOP_CLIENT_ID or WHOOP_CLIENT_SECRET" error

These must always be in your Claude Desktop config - they never expire.

"Failed to refresh token" error

Your refresh token has expired (typically after 30-90 days of non-use). Run node get-tokens.mjs to re-authenticate.

No data returned

• Ensure you've worn your Whoop device and data has synced
• Check that your app has the required scopes authorized

View current persisted tokens

cat tokens.json

Force re-authentication

rm tokens.json
# Then run get-tokens.mjs or add tokens back to Claude config

Security Considerations

Token Storage

• Tokens are stored in tokens.json with restricted permissions (mode 0600 - owner read/write only)
• Windows users: File permissions work differently on Windows and may not provide equivalent protection. Consider additional access controls.
• Tokens are stored unencrypted; ensure your system has appropriate access controls

Configuration Security

• Your claude_desktop_config.json contains your client secret in plain text
• Do not commit this config file to version control
• Consider restricting file permissions on the config file:
  • macOS/Linux: chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Best Practices

• Regularly rotate your Whoop developer app credentials
• Monitor your Whoop account for unauthorized access
• Run npm audit periodically to check for dependency vulnerabilities
• After initial setup, remove WHOOP_ACCESS_TOKEN and WHOOP_REFRESH_TOKEN from your config (they're persisted in tokens.json)

Optional: Custom Token Location

Set WHOOP_TOKEN_PATH environment variable to store tokens in a specific location:

"env": {
  "WHOOP_TOKEN_PATH": "/path/to/secure/tokens.json",
  "WHOOP_CLIENT_ID": "your-client-id",
  "WHOOP_CLIENT_SECRET": "your-client-secret"
}

API Reference

This server uses the Whoop API v2. For more details on the data model and endpoints, see the official documentation.

License

MIT