recovery-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 |
| The current cycle's recovery, last night's sleep and strain so far |
| Daily recovery %, band, HRV, resting heart rate, SpO2, skin temp (default 7 days) |
| Hours asleep vs. needed, stages, performance, consistency, efficiency (naps optional) |
| Day strain, calories, heart rate and steps per cycle |
| Workouts with strain, heart-rate zones, distance; filter by sport |
| Averages, min/max, last 7 days vs. before, and green/yellow/red day counts (default 30 days) |
| Height, weight and the max heart rate WHOOP uses for zones |
| 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'sworkers-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 |
| The MCP endpoint Claude calls (needs a token) |
| Consent page and the return from WHOOP |
| 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 login2. Create the KV namespace
npx wrangler kv namespace create OAUTH_KVPaste 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 deployWrangler 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
Open the WHOOP Developer Dashboard (linked from developer.whoop.com) and sign in with your WHOOP account.
Create a team if asked, then create an app.
Redirect URI:
https://recovery-mcp.<your-subdomain>.workers.dev/callbackScopes:
read:profile,read:body_measurement,read:cycles,read:recovery,read:sleep,read:workout. (offlineis requested by the code to get refresh tokens.)Privacy policy URL: WHOOP asks for one. You can link to
PRIVACY.mdin your copy of this repo.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 deployWrangler prompts for each value. They live in Cloudflare, never in this repo.
6. Add it to Claude
In Claude, open Customize > Connectors, choose + Add, then Add custom connector.
Name it (e.g. "WHOOP") and enter
https://recovery-mcp.<your-subdomain>.workers.dev/mcp.Leave the OAuth client option on the recommended default and choose Continue.
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 pageThen 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 deleteremoves the Worker; delete theOAUTH_KVnamespace 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_trendscall 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 testsFor 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/bodyand/v2/cycle/{id}/recovery. They're all inPATHSinsrc/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…
This server cannot be deployed
Maintenance
Related MCP Connectors
WHOOP recovery, strain, sleep and workouts in Claude via official WHOOP OAuth. Free, open source.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Pace is a remote MCP server that exposes wearable and fitness data to Claude via the Model Context Protocol. It connects to Garmin, Oura, Whoop, Polar, Fitbit and 20+ devices and provides 15 tools for querying sleep, activity, recovery, and training data. Hosted on Google Cloud Run, OAuth 2.1 authentication, Streamable HTTP transport. Instructions: First you need to create an account at: https://pacetraining.co and connect your wearables. After that you can connect the remote Server via Custom Connector in Claude and OAuth 2.1 Flow startet.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that gives Claude access to your WHOOP biometric data — recovery, sleep, strain, and workouts.38 npmMIT
- FlicenseNot gradedqualityDmaintenanceMCP server that wraps the Whoop API v2 to let Claude Code pull workouts, sleep, and recovery data.-
- AlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server connecting Claude to your WHOOP data via the official API, enabling queries for recovery, sleep, cycles, workouts, and profile.MIT
- AlicenseNot gradedqualityDmaintenanceA 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.1MIT