WHOOP MCP Server

WHOOP MCP Server

MCP server for WHOOP biometric data. Query recovery, strain, sleep, workouts, and heart rate from any MCP-compatible AI client.

Two Modes

• Remote — Calls /api/whoop/stats on a deployed WHOOP-connected site (e.g., patrickwingert.com)
• Direct — Talks to the WHOOP API directly with local OAuth + token storage

Both modes expose the same 11 tools through a shared interface.

Setup

1. Build

npm install
npm run build

2. Configure Claude Code

Remote mode (uses an existing WHOOP-connected site):

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/path/to/whoop-mcp-server/dist/index.js"],
      "env": {
        "WHOOP_MODE": "remote",
        "WHOOP_BASE_URL": "https://patrickwingert.com"
      }
    }
  }
}

Direct mode (standalone, talks to WHOOP API):

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

3. Direct Mode — WHOOP Developer Setup

1. Go to WHOOP Developer Portal
2. Create a new application
3. Set redirect URI to http://localhost:8787/callback
4. Enable scopes: read:profile, read:recovery, read:cycles, read:workout, read:sleep, read:body_measurement
5. Copy Client ID and Client Secret to your config

4. Direct Mode — OAuth Flow

On first use, the server will need OAuth tokens. The OAuth flow:

1. Server starts a temporary listener on localhost:8787
2. Open the generated authorization URL in your browser
3. Authorize on WHOOP's site
4. Tokens are stored in ~/.whoop-mcp/tokens.json (chmod 600)
5. Tokens auto-refresh going forward

Tools

Tier 1 — Biometric Data (read-only)

| Tool | Description | |------|-------------| | whoop_get_stats | Full biometric snapshot (recovery, strain, HR, sleep, workout) | | whoop_get_recovery | Recovery score (0-100), resting HR, HRV, SpO2, skin temp | | whoop_get_strain | Daily strain (0-21), kilojoules, average/max HR | | whoop_get_workout | Latest workout: sport, duration, strain, HR zones, distance | | whoop_get_heart_rate | Current HR with source context (resting/workout/decay) | | whoop_get_sleep | Sleep performance, stages, efficiency, respiratory rate | | whoop_get_sleep_need | Sleep need breakdown: baseline, debt, strain impact, nap offset |

Tier 2 — Diagnostics

| Tool | Description | |------|-------------| | whoop_check_health | Endpoint status, token expiry, connection state | | whoop_get_cache_status | What's cached, staleness, TTL remaining | | whoop_invalidate_cache | Force fresh data on next request | | whoop_get_config | Current mode, target, scopes, cache TTL |

All tools support response_format: markdown (default, human-readable) or json (structured data).

Environment Variables

| Variable | Mode | Required | Description | |----------|------|----------|-------------| | WHOOP_MODE | Both | Yes | remote or direct | | WHOOP_BASE_URL | Remote | Yes | Base URL of WHOOP-connected app | | WHOOP_CLIENT_ID | Direct | Yes | From WHOOP developer dashboard | | WHOOP_CLIENT_SECRET | Direct | Yes | From WHOOP developer dashboard |

Local Storage (Direct Mode)

~/.whoop-mcp/
├── tokens.json      # OAuth tokens (chmod 600)
└── cache.json       # Cached API responses

Testing

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js