---
title: WHOOP MCP for AI Agents: OAuth, Recovery, Sleep and Strain
description: Connect WHOOP recovery, HRV, sleep, cycles, strain and workouts to an AI agent through a local-first OAuth v2 MCP server.
canonical: https://wellness.delx.ai/guides/whoop-mcp-for-ai-agents
content_signal: ai-train=no, search=yes, ai-input=yes
---

# WHOOP MCP for AI Agents

The WHOOP MCP server 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.

## Short answer

Create a WHOOP Developer app with <code>http://127.0.0.1:3000/callback</code>, run <code>npx -y whoop-mcp-unofficial setup</code>, then <code>npx -y whoop-mcp-unofficial auth</code> and <code>npx -y whoop-mcp-unofficial doctor</code>. OAuth tokens stay local. Start with daily or weekly summaries and preserve WHOOP score states instead of treating every record as complete.

## Setup method

1. Create a WHOOP Developer application and register the local callback.
2. Run <code>npx -y whoop-mcp-unofficial setup</code>; use the interactive flow so the client secret does not enter shell history.
3. Run <code>npx -y whoop-mcp-unofficial auth</code> and review the requested scopes.
4. Run <code>npx -y whoop-mcp-unofficial doctor</code>, then call <code>whoop_connection_status</code>, <code>whoop_data_inventory</code> and <code>whoop_privacy_audit</code>.
5. Start with <code>whoop_daily_summary</code> or <code>whoop_weekly_summary</code>. Use collections only for a narrow time range.

Default read-only scopes:

<code>read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement</code>

## MCP client configuration

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

## Data availability

- Recovery score, HRV, RHR, SpO2, skin temperature: available. Available when WHOOP returns a scored recovery.
- Sleep sessions, stages and performance: available. All scored sleep records.
- Cycles, day strain and kilojoules: available. Physiological cycle records.
- Workouts, sport and heart-rate zones: available. All recorded workouts exposed by the public API.
- Profile and body measurements: available. Height, weight and max heart rate.
- Continuous heart-rate or live BLE telemetry: not_available. Not exposed by the public WHOOP API; this connector is not a Bluetooth listener.

WHOOP records expose <code>score_state</code>. <code>SCORED</code> has calculated fields, <code>PENDING_SCORE</code> is still being evaluated and <code>UNSCORABLE</code> has no valid score. Missing physiology must not be inferred.

## Safe first-call sequence

1. <code>whoop_connection_status</code>
2. <code>whoop_data_inventory</code>
3. <code>whoop_privacy_audit</code>
4. <code>whoop_daily_summary</code>
5. <code>whoop_list_recoveries</code>

## Privacy and revocation

- Read-only by default.
- OAuth secrets and refresh tokens stay on the user's machine or server.
- Collection tools support summary, structured and raw response formats.
- The connector distinguishes upstream raw JSON from raw sensor telemetry.
- Profile and goals persist locally to ~/.delx-wellness/profile.json (mode 0600); shared with all 14 Delx Wellness connectors and never uploaded.

OAuth configuration and tokens are stored in user-only local files and are never returned through MCP tools. The only destructive connector action is revocation; <code>whoop_revoke_access</code> requires <code>explicit_user_intent=true</code> before deleting the local tokens and revoking the grant.

## Pagination and rate limits

WHOOP collection endpoints return at most 25 records per page and use <code>next_token</code>. Use narrow timezone-aware start/end values, continue only while a token exists and cap all-pages calls.

WHOOP currently documents default limits of 100 requests per minute and 10,000 requests per day. Treat live <code>X-RateLimit-*</code> headers as authority, cache repeated GETs and use v2 webhooks 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.

## Official sources

- OAuth 2.0: https://developer.whoop.com/docs/developing/oauth/
- WHOOP API v2: https://developer.whoop.com/api/
- Rate limits: https://developer.whoop.com/docs/developing/rate-limiting/
- Pagination: https://developer.whoop.com/docs/developing/pagination/
- Webhooks: https://developer.whoop.com/docs/developing/webhooks/

## Canonical Delx sources

- Connector specification: https://wellness.delx.ai/connectors/whoop
- Connector comparison: https://wellness.delx.ai/guides/choose-wellness-mcp-connector
- Security model: https://wellness.delx.ai/security
- npm: https://www.npmjs.com/package/whoop-mcp-unofficial
- GitHub: https://github.com/davidmosiah/whoop-mcp

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