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