# Whoop MCP Server

A small personal server that lets Claude read your Whoop recovery, sleep,
cycle, and workout data. Once it's running, you can ask Claude things like
"pull my recovery for this week" and it will fetch real numbers from Whoop.

It does **not** need to know about your menstrual cycle dashboard — you stay
in the loop: ask Claude to pull your Whoop data, then ask it to write a
summary into your dossier artifact.

## How it works

- You log in to Whoop **once**, in your browser, directly on this server.
- The server stores your Whoop tokens and refreshes them automatically.
- Claude talks to this server over one endpoint: `/mcp`.
- This server talks to Whoop's real API on your behalf.

```
You ──(one-time login)──> this server ──(OAuth)──> Whoop
Claude ──(tool calls)──> this server ──(API calls)──> Whoop
```

## 1. Create a Whoop developer app

1. Go to <https://developer-dashboard.whoop.com> and sign in with your Whoop account.
2. Create a Team (if prompted), then create an App.
3. Note your **Client ID** and **Client Secret**.
4. Add a **Redirect URL**. It must be:
   `https://YOUR-DEPLOYED-URL/auth/whoop/callback`
   (You'll know your real URL after step 3 below — you can come back and edit this.)
5. Request these scopes: `read:recovery`, `read:cycles`, `read:sleep`,
   `read:workout`, `read:profile`, `read:body_measurement`, `offline`.

## 2. Configure

```bash
cp .env.example .env
```

Fill in `WHOOP_CLIENT_ID`, `WHOOP_CLIENT_SECRET`, and `WHOOP_REDIRECT_URI`
(this last one must exactly match what you registered in step 1, including
`https://` and no trailing slash).

## 3. Run it somewhere reachable on the internet

Claude connects to this server from Anthropic's cloud, not from your laptop —
so it needs a real public HTTPS URL. Any standard Node.js host works
(Render, Railway, Fly.io, a small VPS, etc.):

```bash
npm install
npm start
```

Set the same environment variables from `.env` in your host's dashboard.
The app listens on `process.env.PORT` (most hosts set this for you
automatically).

**About storage:** by default, your Whoop tokens are saved to a local file
(`./data/whoop-tokens.json`). If your host wipes its disk between restarts
(common on some free tiers), you'll need to redo the one-time login after
every restart — or set `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`
(Upstash has a free tier) so tokens are stored durably instead. No code
changes needed, just those two environment variables.

Once deployed, go back to your Whoop app settings and make sure the
Redirect URL matches your live URL exactly.

## 4. Connect your Whoop account (one time)

Visit `https://YOUR-DEPLOYED-URL/auth/whoop/start` in a browser, log in to
Whoop, and approve access. You'll see a confirmation page when it's done.

## 5. Add this server to Claude

1. In Claude, go to **Settings → Connectors**.
2. Click **Add custom connector**.
3. Paste: `https://YOUR-DEPLOYED-URL/mcp`
4. Click **Add**, then enable it for your conversation (the "+" button →
   Connectors).

You can now ask Claude things like:
- "What was my recovery this morning?"
- "Pull my last 7 days of sleep data."
- "Compare my strain over the last 2 weeks."

## Security, honestly

This server doesn't have its own login wall on the `/mcp` endpoint — it's
protected only by the URL being private to you. Treat the URL like a
password:
- Don't share it or post it anywhere public.
- Don't commit `.env` to a public GitHub repo (`.gitignore` already excludes it).
- If you want stronger protection later (e.g. real per-request auth), that's
  a reasonable next step — just ask and we can add it.

## Troubleshooting

If something breaks — a deploy error, a 401 from Whoop, Claude saying the
connector won't connect — copy the exact error message back to Claude and
we'll fix it together. This code was written without the ability to run or
deploy it directly, so the first run-through is where real-world issues
(dependency versions, host quirks) tend to surface.