recovery-mcp
by ejochims
README.md
# recovery-mcp
An unofficial, read-only [MCP](https://modelcontextprotocol.io) 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?"
## 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`](https://github.com/cloudflare/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
```bash
git clone <this repo> recovery-mcp && cd recovery-mcp
npm install
npx wrangler login
```
### 2. Create the KV namespace
```bash
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
```bash
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](https://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
```bash
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:
```bash
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
```bash
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](https://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](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues