WHOOP → Claude connector

A personal remote MCP server that gives Claude read-only access to your WHOOP data: recovery, sleep, day strain, workouts and body measurements.

Built as a Next.js app on Vercel with Supabase for token storage. Single-user by design — this is not a directory-listed connector.

---

Why there is an OAuth server in here

WHOOP's OAuth server doesn't support Dynamic Client Registration and doesn't publish RFC 8414 discovery metadata — apps are registered by hand in the WHOOP developer dashboard. Claude, on the other hand, discovers an authorization server from the MCP server's own origin and registers itself dynamically.

So this app bridges the two: it is a small OAuth authorization server in its own right, and brokers the real exchange with WHOOP behind it.

Claude  ──/authorize──▶  this app  ──▶  WHOOP consent screen
                              ◀── /callback (WHOOP auth code)
                              │    exchanges it with the WHOOP client secret,
                              │    stores WHOOP tokens encrypted in Supabase
Claude  ◀── our own auth code ─┘
Claude  ──/token──────▶  this app  ──▶  our own opaque bearer token
Claude  ──/mcp────────▶  this app  ──▶  WHOOP API v2 (using the stored tokens)

The WHOOP client secret and the raw WHOOP tokens never leave the server. Claude only ever holds a bearer token that this app issued, which is a lookup key into a row we can revoke at any time.

---

Endpoints

Path	Purpose
POST /mcp	The MCP endpoint. This is the URL you paste into Claude.
GET /.well-known/oauth-protected-resource[/mcp]	RFC 9728 protected resource metadata
GET /.well-known/oauth-authorization-server[/mcp]	RFC 8414 authorization server metadata
POST /register	RFC 7591 Dynamic Client Registration (fallback when a client can't use CIMD)
GET /authorize	Start of the bridged authorization flow
GET /callback	WHOOP's redirect target — register this in the WHOOP dashboard
POST /token	Token exchange and refresh
POST /api/webhooks/whoop	Optional WHOOP webhook receiver (signature-verified, currently a no-op)
GET /	Status page — shows which env vars are set, never their values

initialize and tools/list work without authentication, so Claude can connect and inspect the server before you sign in. The first tools/call returns 401 with a WWW-Authenticate header, which is what makes Claude show an inline Connect card instead of a failed tool call.

---

Tools

Tool	What it returns
get_daily_summary	One day's cycle, recovery and sleep in a single call. Start here.
get_trends	Rolling averages over N days vs the N before: recovery, HRV, RHR, sleep, strain, plus the 7-day:28-day training load ratio
get_recovery	Recovery %, resting HR, HRV (RMSSD), SpO2, skin temperature
get_sleep	Time in bed, light/deep/REM split, performance, efficiency, sleep debt
get_strain	Day strain (0–21), calories, average/max HR
get_workouts	Sport, duration, strain, HR zones, distance, elevation
get_profile	Name, email, height, weight, max HR

All are marked readOnlyHint — nothing here writes to WHOOP. Responses are normalized: durations in minutes, energy in kilocalories, distances in meters, and WHOOP's nested score objects flattened.

get_trends takes window_days (3-30, default 7) instead, and fetches twice that span so the window has a baseline to be compared against. The training load ratio is separate from that window: it is always the last 7 days of day strain over the last 28, the spans the acute:chronic ratio is defined for, so cycles are fetched over 28 days even when the window is shorter. The day still in progress is left out of the strain and calorie averages — WHOOP scores the current cycle as the day goes, and counting a half-finished day as a whole one understates both the mean and the ratio. Naps are left out of the sleep averages, and records WHOOP has not scored — or recoveries taken while the strap was still calibrating — are left out of every average.

Date arguments accept date (YYYY-MM-DD, resolved in WHOOP_TIMEZONE), explicit start/end ISO-8601 instants, or days to look back from now. Pagination is handled internally, so a tool returns the whole range rather than WHOOP's first page of ten.

---

Setup

1. WHOOP app

You need an active WHOOP membership to use the developer platform at all.

1. Create a team and an app at https://developer-dashboard.whoop.com.
2. Enable scopes: read:cycles, read:sleep, read:recovery, read:workout, read:profile, read:body_measurement, and offline — without offline WHOOP issues no refresh token and the connector dies after an hour.
3. Register the redirect URI: https://<your-domain>/callback
4. Copy the Client ID and Client Secret.

2. Supabase

Run the migrations in supabase/migrations/ in order against your project (paste them into the SQL editor, or supabase db push). They create five tables, enable RLS with no policies — so only the service role key can read them — and add a prune_expired_oauth_rows() housekeeping function that only the service role may execute.

3. Environment

Copy .env.example to .env.local and fill it in:

cp .env.example .env.local
openssl rand -base64 32   # -> TOKEN_ENCRYPTION_KEY

APP_BASE_URL must be the public HTTPS origin with no trailing slash, and must match what you type into Claude. Set the same variables in the Vercel project.

ALLOWED_WHOOP_USER_ID locks the connector to your WHOOP account. You don't need to know it up front: leave it empty, connect once, and the sign-in page refuses the account and shows the id to set. Redeploy and connect again.

4. Deploy

npm install
npm run build
vercel deploy --prod

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗