Skip to main content
Glama
recovery-mcp
by ejochims

recovery-mcp

An unofficial, read-only MCP server that lets Claude answer questions about your own WHOOP data (recovery, sleep, strain, workouts, body measurements). It runs on Cloudflare Workers and you add it to Claude as a custom connector.

Unofficial. This is a personal, community project. It is not made, endorsed or supported by WHOOP, Inc. "WHOOP" is a trademark of WHOOP, Inc. and is used here only to say which API the code talks to.

Not medical advice. The tools pass along numbers WHOOP has already computed. Nothing here diagnoses or treats anything.

What Claude can do with it

Tool

What it returns

whoop_today

The current cycle's recovery, last night's sleep and strain so far

whoop_recovery

Daily recovery %, band, HRV, resting heart rate, SpO2, skin temp (default 7 days)

whoop_sleep

Hours asleep vs. needed, stages, performance, consistency, efficiency (naps optional)

whoop_strain

Day strain, calories, heart rate and steps per cycle

whoop_workouts

Workouts with strain, heart-rate zones, distance; filter by sport

whoop_trends

Averages, min/max, last 7 days vs. before, and green/yellow/red day counts (default 30 days)

whoop_body

Height, weight and the max heart rate WHOOP uses for zones

whoop_check_connection

Calls each WHOOP endpoint once and says which ones answer

Every tool is read-only and marked that way for Claude. Day ranges go up to 180.

Ask things like "How did I sleep this week?", "Is my HRV trending up?" or "How many runs did I do in the last month and what was my average strain?"

Related MCP server: whoop-mcp

How it works

Claude ──OAuth──▶ this Worker ──OAuth──▶ WHOOP
       ◀─ tools ─┘             ◀─ data ─┘
  • The Worker is its own OAuth server. Claude has to sign in before it can call /mcp; there is no open URL. This uses Cloudflare's workers-oauth-provider.

  • Signing in sends you to WHOOP. After WHOOP approves, the Worker checks that the WHOOP account is yours (ALLOWED_WHOOP_USER_ID) and refuses anyone else. If that secret isn't set, nobody gets in.

  • Your WHOOP tokens are stored only inside the encrypted grant that the OAuth library keeps in Workers KV. When Claude refreshes its token, the Worker refreshes the WHOOP token too (WHOOP rotates refresh tokens on every use).

  • No health data is stored or logged. Each tool call fetches from WHOOP, summarizes and returns. Errors log only an error name or HTTP status.

Path

What it is

/mcp

The MCP endpoint Claude calls (needs a token)

/authorize, /callback

Consent page and the return from WHOOP

/oauth/token, /oauth/register, /.well-known/*

Standard OAuth endpoints Claude uses

Code tour: src/index.ts wires it together, src/auth-handler.ts is the sign-in flow, src/whoop.ts is the WHOOP API client, src/tools.ts defines the tools and src/summaries.ts turns raw records into readable numbers.

Setup

You need Node 20+, a free Cloudflare account, and a WHOOP membership.

1. Install

git clone <this repo> recovery-mcp && cd recovery-mcp
npm install
npx wrangler login

2. Create the KV namespace

npx wrangler kv namespace create OAUTH_KV

Paste the id it prints into wrangler.jsonc in place of REPLACE_WITH_YOUR_KV_NAMESPACE_ID.

3. Deploy once to get your URL

npx wrangler deploy

Wrangler prints a URL like https://recovery-mcp.<your-subdomain>.workers.dev. Put that URL plus /mcp into MCP_RESOURCE in wrangler.jsonc, for example https://recovery-mcp.alex.workers.dev/mcp.

4. Register your WHOOP app

  1. Open the WHOOP Developer Dashboard (linked from developer.whoop.com) and sign in with your WHOOP account.

  2. Create a team if asked, then create an app.

  3. Redirect URI: https://recovery-mcp.<your-subdomain>.workers.dev/callback

  4. Scopes: read:profile, read:body_measurement, read:cycles, read:recovery, read:sleep, read:workout. (offline is requested by the code to get refresh tokens.)

  5. Privacy policy URL: WHOOP asks for one. You can link to PRIVACY.md in your copy of this repo.

  6. Copy the client ID and client secret.

5. Store the secrets

npx wrangler secret put WHOOP_CLIENT_ID
npx wrangler secret put WHOOP_CLIENT_SECRET
npx wrangler deploy

Wrangler prompts for each value. They live in Cloudflare, never in this repo.

6. Add it to Claude

  1. In Claude, open Customize > Connectors, choose + Add, then Add custom connector.

  2. Name it (e.g. "WHOOP") and enter https://recovery-mcp.<your-subdomain>.workers.dev/mcp.

  3. Leave the OAuth client option on the recommended default and choose Continue.

  4. Approve the consent page, then sign in to WHOOP.

7. Lock it to your WHOOP account

The first sign-in stops on a page that shows your WHOOP user id, because no owner is set yet. Set it and connect again:

npx wrangler secret put ALLOWED_WHOOP_USER_ID   # paste the id from that page

Then ask Claude to run whoop_check_connection. Every line should say ok.

Work accounts: a company Claude workspace may not allow personal custom connectors. Use a personal Claude account.

Revoking access

  • From Claude: remove the connector in Customize > Connectors.

  • From WHOOP: delete the app, or rotate its client secret, in the WHOOP Developer Dashboard. Existing tokens then stop working.

  • Everything: npx wrangler delete removes the Worker; delete the OAUTH_KV namespace in the Cloudflare dashboard to remove the stored grants.

Limits

  • Cloudflare free plan: 100,000 requests a day and 10 ms of CPU per request. A long whoop_trends call is the heaviest; if Cloudflare reports CPU limit errors, the Workers Paid plan raises the limit.

  • WHOOP: 100 requests a minute and 10,000 a day. The client waits and retries on a 429 and pages 25 records at a time.

Development

cp .dev.vars.example .dev.vars   # git-ignored; fill in for local runs
npm run dev                      # local Worker on http://localhost:8787
npm run check                    # typecheck and unit tests

For a local run, set MCP_RESOURCE to http://localhost:8787/mcp and add http://localhost:8787/callback as a second redirect URI in your WHOOP app.

Not yet verified against the live API

The tests use recorded response shapes from WHOOP's API reference, not live calls. These are the parts most likely to need a small fix; whoop_check_connection shows which one:

  • The API base (https://api.prod.whoop.com/developer) and the v2 paths /v2/user/profile/basic, /v2/user/measurement/body and /v2/cycle/{id}/recovery. They're all in PATHS in src/whoop.ts.

  • The real WHOOP code exchange and refresh-token rotation.

  • The full sign-in with Claude's connector.

WHOOP's terms

Read WHOOP's API Terms of Use (on developer.whoop.com) before using or forking this. In short: keep your client secret out of any repo, don't store WHOOP data beyond what's needed (this server stores none), don't use it to train AI models, and don't present the project as made or endorsed by WHOOP.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that gives Claude access to your WHOOP biometric data — recovery, sleep, strain, and workouts.
      38 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Self-hosted MCP server connecting Claude to your WHOOP data via the official API, enabling queries for recovery, sleep, cycles, workouts, and profile.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that connects Claude to the WHOOP Developer API, allowing natural language queries about recovery, sleep, strain, workouts, and body measurements. All data stays on your machine with read-only access.
      1
      MIT