Provider guide · Recovery and sleep MCP

WHOOP MCP for AI agents

Give an MCP-compatible agent bounded access to WHOOP recovery, HRV, sleep, cycles, strain and workouts through the official API, while keeping OAuth credentials and sensitive health records local.

Short answer

Create a WHOOP Developer app, run npx -y whoop-mcp-unofficial setup, then npx -y whoop-mcp-unofficial auth and npx -y whoop-mcp-unofficial doctor. The connector uses the official WHOOP OAuth API v2. OAuth tokens stay local. Start with daily or weekly summaries and preserve upstream score states instead of treating every record as complete.

Setup method

Connect WHOOP in five controlled steps

1
Create a WHOOP Developer app
Create an OAuth application in the WHOOP Developer Dashboard and register http://127.0.0.1:3000/callback. Keep the client secret private.
2
Run the local setup
Run npx -y whoop-mcp-unofficial setup. The interactive flow stores the client configuration locally with user-only file permissions.
3
Complete OAuth authorization
Run npx -y whoop-mcp-unofficial auth, review the requested read scopes (read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement) and approve only the intended account access.
4
Verify auth and privacy
Run npx -y whoop-mcp-unofficial doctor, then call whoop_connection_status, whoop_data_inventory and whoop_privacy_audit before requesting health records.
5
Start with bounded summaries
Call whoop_daily_summary or whoop_weekly_summary first. Use collection tools with a narrow time range and next_token only when detailed records are necessary.

Install, authorize and verify

setup

npx -y whoop-mcp-unofficial setup

authorize

npx -y whoop-mcp-unofficial auth

verify

npx -y whoop-mcp-unofficial doctor

MCP client configuration

Add the standalone process only after local OAuth and doctor succeed.

mcp-client.json

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "whoop-mcp-unofficial"]
    }
  }
}

What the agent can use

Recovery

Recovery score, HRV, resting heart rate, SpO2 and skin temperature when WHOOP returns a scored record.

Sleep

Sleep sessions, stages, performance, consistency, efficiency and sleep need from supported records.

Cycles and strain

Physiological cycles, day strain, heart rate and kilojoules without forcing activity into calendar-day assumptions.

Workouts

Recorded workouts, sport, strain, heart-rate zones and distance fields when present upstream.

Respect score_state: SCORED has calculated metrics, PENDING_SCORE is still being evaluated and UNSCORABLE has no valid score. Missing physiology must stay missing; an agent must not infer it.

Safe first-call sequence

1. whoop_connection_status
2. whoop_data_inventory
3. whoop_privacy_audit
4. whoop_daily_summary
5. whoop_list_recoveries

Privacy boundary

OAuth config and tokens stay in user-only local files and never appear in MCP responses.
The default scopes are read-only: read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement.
Structured mode removes secret-bearing and location fields while preserving useful physiology.
Revocation is destructive and requires explicit_user_intent=true before deleting local tokens and the grant.

Pagination, scores and rate limits

WHOOP collection endpoints return at most 25 records per page and use next_token. Prefer a narrow timezone-aware start/end window, continue only while a token exists and cap all-pages workflows.

WHOOP currently documents default limits of 100 requests per minute and 10,000 requests per day. Treat the live X-RateLimit-* headers as authority, cache repeated GETs and use v2 webhooks for hosted change detection instead of polling full history.

In this connector, raw means the upstream WHOOP API JSON for a supported endpoint. Continuous heart-rate and raw device telemetry are not exposed; the connector is not a BLE listener.

WHOOP MCP questions

What is the WHOOP MCP server?

whoop-mcp-unofficial is a local-first bridge between the official WHOOP OAuth API v2 and an MCP-compatible AI agent. It exposes authorized recovery, sleep, cycle, workout, profile and body-measurement records without returning OAuth tokens to the model.

Which WHOOP OAuth scopes does the connector request?

Its default read-only scope set is read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement. The offline scope may be added when refresh-token access is needed. Request only the data domains the workflow actually uses and review the consent screen before approval.

Why can a WHOOP recovery or sleep score be missing?

WHOOP records include a score_state. SCORED means the score fields are available; PENDING_SCORE means WHOOP is still evaluating the record; UNSCORABLE means the upstream service could not calculate it. An agent must preserve that state instead of inventing a score.

Does WHOOP MCP expose continuous heart-rate samples?

No. Continuous heart-rate and raw device telemetry are not exposed by the official WHOOP developer API. In this connector, raw means the upstream WHOOP API JSON for a supported record, not second-by-second sensor samples, accelerometer data or BLE collection.

What rate limits should a WHOOP agent expect?

WHOOP currently documents default limits of 100 requests per minute and 10,000 requests per day. Read the live X-RateLimit headers, paginate with next_token, cache repeated reads and avoid full-history polling loops.

Is this an official WHOOP product or medical advice?

No. Delx Wellness and whoop-mcp-unofficial are not affiliated with WHOOP. Recovery and sleep data can support personal reflection and training context, but this connector is not medical advice, diagnosis, treatment or emergency monitoring.

Canonical and official sources

WHOOP connector specification WHOOP OAuth 2.0 WHOOP API v2 reference WHOOP API rate limits WHOOP pagination WHOOP v2 webhooks Machine-readable Markdown

Delx Wellness and whoop-mcp-unofficial are not affiliated with WHOOP. This page provides technical wellness integration context, not medical advice.