[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82866":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":14,"starSnapshotCount":14,"syncStatus":15,"lastSyncTime":34,"discoverSource":35},82866,"whoop-mcp","briangaoo\u002Fwhoop-mcp","briangaoo","Model Context Protocol server giving Claude (or any MCP client) full read + write access to your Whoop fitness data via the private reverse-engineered iOS API. 47 tools: recovery, sleep, strain, HRV trends, Strength Trainer, journal, Whoop Coach, and smart alarm. TypeScript + zod, auto-refresh Cognito auth.",null,"TypeScript",61,12,3,0,2,6,3.34,"Other",false,"main",true,[23,24,25,26,27,28,29,30],"anthropic","claude","fitness","mcp","model-context-protocol","reverse-engineered","typescript","whoop","2026-06-12 02:04:28","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fbanner.svg\" alt=\"whoop-mcp — 48 tools, 47 microservices, 311 endpoints\" width=\"820\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ci>Give Claude (or any MCP-compatible AI) \u003Cb>full read + write access to your Whoop fitness data\u003C\u002Fb> by wrapping Whoop's private iOS API.\u003C\u002Fi>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#remote-hosting\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Code-a855f7?style=for-the-badge\" alt=\"Claude Code\">\u003C\u002Fa>\n  \u003Ca href=\"#claude-desktop-config\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude_Desktop-7c3aed?style=for-the-badge\" alt=\"Claude Desktop\">\u003C\u002Fa>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FChatGPT_Desktop-10a37f?style=for-the-badge\" alt=\"ChatGPT Desktop\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FCodex-000000?style=for-the-badge\" alt=\"Codex\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGemini_CLI-4285f4?style=for-the-badge\" alt=\"Gemini CLI\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FAny_MCP_1.x_Client-262626?style=for-the-badge\" alt=\"any MCP 1.x client\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftools-48-9ca3af?style=flat-square\" alt=\"tools\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-6.0-3178c6?style=flat-square&logo=typescript&logoColor=white\" alt=\"typescript\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\" alt=\"node\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-1.x%2B-9ca3af?style=flat-square\" alt=\"mcp\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdeploy-Fly%20%7C%20Docker%20%7C%20Railway-9ca3af?style=flat-square\" alt=\"deploy\">\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cvideo src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fb0101d7d-24ad-4341-a88c-dc6fae075f6e\" controls muted width=\"820\">\u003C\u002Fvideo>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Csub>▶ 2-min demo — the full \u003Ccode>whoop-mcp cloud\u003C\u002Fcode> flow: install → Whoop login → Fly deploy → Claude connector → first query.\u003C\u002Fsub>\n\u003C\u002Fp>\n\n48 tools, structured zod-validated outputs, bundled catalogs (372 exercises, 308 behaviors, 203 sports, 311 endpoints), write-safety harness, automatic Cognito token refresh, session-scoped catalog gate. TypeScript 6, Node 24, 212 tests.\n\n> *Note: this works through Whoop's private iOS API rather than the public OAuth API. That isn't what Whoop's terms allow — see the [FAQ](#faq) if you want the full picture before installing.*\n\n---\n\n## Table of contents\n\n1. [Get Started](#get-started)\n2. [Why this exists](#why-this-exists)\n3. [What it does](#what-it-does)\n4. [Architecture](#architecture)\n5. [The 48 tools](#the-48-tools)\n6. [Authentication](#authentication)\n7. [Write-safety harness](#write-safety-harness)\n8. [Bundled catalogs](#bundled-catalogs)\n9. [Configuration](#configuration)\n10. [Remote hosting](#remote-hosting)\n11. [The `whoop-mcp` CLI](#the-whoop-mcp-cli)\n12. [Privacy + security](#privacy--security)\n13. [Troubleshooting](#troubleshooting)\n14. [Comparison to alternatives](#comparison-to-alternatives)\n15. [FAQ](#faq)\n16. [Disclaimers](#disclaimers)\n17. [Acknowledgments](#acknowledgments)\n\n**Other root-level docs:** [`TOOLS.md`](TOOLS.md) (full per-tool reference) · [`WHOOP.md`](WHOOP.md) (full API reference) · [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`SECURITY.md`](SECURITY.md) · [`LICENSE`](LICENSE)\n\n---\n\n## Get Started\n\n**Prerequisites:** Node 24+ and a Whoop account (any membership tier).\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fbriangaoo\u002Fwhoop-mcp.git\ncd whoop-mcp && npm install && npx tsc && npm link\n```\n\nThat puts `whoop-mcp` on your PATH (the one-time `npx tsc` builds it; after that every workflow is a `whoop-mcp` command — there are no `npm run` scripts). Now run **one guided command** — each handles Whoop login (SMS included), setup, and connecting to Claude from end to end. Pick how you want to run it:\n\n### ★ Recommended — `whoop-mcp cloud`\n\nDeploys the server to a host and connects it to Claude on **web, desktop, and mobile**, synced across every device on your account. One command walks through:\n\n1. **Whoop login** — email + password, plus the SMS code if your account has MFA. Tokens are saved locally and pushed to the host.\n2. **Pick a host** — Fly (automated + tested), Railway, Google Cloud Run, or your own server (guided Docker steps).\n3. **Secrets** — generates `MCP_AUTH_TOKEN` and asks you to choose a connector password.\n4. **Deploy + verify** — sets env, deploys, confirms `\u002Fhealth` and the OAuth endpoints are live.\n5. **Connect** — prints ready-to-paste setup for **claude.ai, ChatGPT, Claude Code (remote), and Cursor \u002F Windsurf \u002F any HTTP MCP client** (URL + password for the OAuth connectors, a bearer-token block for the rest), and opens claude.ai's connector page.\n\n```bash\nwhoop-mcp cloud\n```\n\n### Local only — `whoop-mcp local`\n\nRuns the server on this machine over stdio — no hosting, this device only. Walks through Whoop login → build → wiring it into the client you pick: **Claude Desktop, Claude Code, Cursor, VS Code (Copilot), Gemini CLI, Codex CLI, or Windsurf** — it writes the right config to the right path automatically (or prints a universal block for any other MCP client). Restart the client and you're set.\n\n```bash\nwhoop-mcp local\n```\n\n### Keeping it alive\n\nWhoop's tokens expire roughly every 30 days. When they do, re-run the same command — it re-logs you in and (if you deployed) pushes the new tokens to your server:\n\n```bash\nwhoop-mcp auth\n```\n\nSilent if your account has no SMS MFA; prompts for the code if it does. Pushes fresh tokens to your deployment automatically.\n\n### Check it works\n\nAsk Claude: *\"how am I doing today on whoop?\"* — you should get structured recovery \u002F sleep \u002F strain back.\n\n> Prefer to wire everything up by hand? The guided commands just automate the steps documented in [The `whoop-mcp` CLI](#the-whoop-mcp-cli), [Remote hosting](#remote-hosting), and [Configuration](#configuration). Stuck? See [Troubleshooting](#troubleshooting).\n\n---\n\n## Why this exists\n\nWhoop ships two APIs:\n\n- The **public developer API** at [`developer.whoop.com`](https:\u002F\u002Fdeveloper.whoop.com\u002Fapi\u002F) is OAuth2, read-only, and exposes **13 endpoints** under 6 scopes. You get recovery score, sleep stage totals, workout strain, body measurements (3 fields), and HRV\u002FRHR per cycle. No journal, no Strength Trainer, no Whoop Coach, no hypnogram, no stress monitor, no trends, no writes, nothing else. Numeric `sport_id` was removed 2025-09-01.\n- The **private iOS API** is what the actual Whoop app uses — `api.prod.whoop.com` behind AWS Cognito. **311 distinct operations across 47 microservices**, including everything missing from above.\n\nThis MCP wraps the iOS surface.\n\n### What the iOS API has that the public OAuth doesn't\n\n| Capability | Tool |\n|---|---|\n| HRV \u002F RHR \u002F respiratory \u002F VO2 \u002F weight time-series (25 metrics × up to 4 windows) | `whoop_trend` |\n| Hypnogram (per-stage sleep timeline) + full stage breakdown (ms + %) + in-sleep HR | `whoop_sleep` |\n| Strength Trainer — every set, every workout, full 372-exercise catalog, PRs | `whoop_lift_*` (8 tools) |\n| 308-behavior Journal + behavior impact analysis | `whoop_journal*` (5 tools) |\n| Stress monitor (intraday timeline) | `whoop_stress, whoop_live_stress` |\n| Whoop Coach AI chat | `whoop_coach_ask` |\n| Smart Alarm (read + 4 write modes) | `whoop_smart_alarm*` |\n| HR zones (read + configure max HR \u002F 5 custom zones) | `whoop_hr_zones*` |\n| Compare-windows, sleep coach, calendar grid, performance assessment | `whoop_compare`, `whoop_sleep_need`, `whoop_calendar`, `whoop_performance_assessment` |\n| Live HR \u002F activity state \u002F live stress | `whoop_live_*` (3 tools) |\n| Community leaderboards, hidden metrics, women's health (cycle \u002F symptoms \u002F MCI) | `whoop_leaderboard`, `whoop_hidden_metric`, `whoop_cycle*` |\n| **14 write tools** — log workouts, journal entries, profile edits, smart-alarm config | various |\n\nIf recovery + sleep totals + workout list is enough for you, use the public OAuth API. If anything in the table is interesting, you need this. The iOS API was discovered via mitmproxy — full methodology in [`WHOOP.md`](WHOOP.md).\n\n---\n\n## What it does\n\nThe MCP runs as a local Node process. It speaks **Model Context Protocol** over stdio (or HTTP for remote deployments), registers 48 tools at startup, and waits for tool calls from a connected MCP client.\n\nWhen a tool is called:\n\n1. Authenticates via the cached Cognito access token (auto-refreshes if expired)\n2. Issues HTTP requests to `api.prod.whoop.com`\n3. Walks the response to extract a flat domain object (the **projection** step)\n4. Validates the projected object against a zod schema (catches Whoop API drift)\n5. Returns the structured JSON to the MCP client\n\nWrites follow the same path plus a **preview gate**: every write tool defaults `confirm: false`, returning a preview of what would be sent. Claude must explicitly re-call with `confirm: true` to fire.\n\nSee [The 48 tools](#the-48-tools) for the full per-tool reference.\n\n---\n\n## Architecture\n\n```\nClaude Desktop \u002F Code  ──stdio──▶  src\u002Fserver.ts  ──▶  48 tool handlers\n                                                          │\n                                       ┌──────────────────┼──────────────────┐\n                                       ▼                  ▼                  ▼\n                                  schemas (zod)    projections (raw→flat)  whoop\u002Fclient\n                                                                              │\n                                                                              ▼ HTTPS\n                                                                       api.prod.whoop.com\n```\n\n### Three layers per tool\n\nEvery tool is a schema + projection + handler:\n\n- **`src\u002Fschemas\u002F\u003Ctool>.ts`** — zod schema. The contract Claude sees. Used at runtime to validate the projection's output before returning.\n- **`src\u002Fprojections\u002F\u003Ctool>.ts`** — pure function turning Whoop's raw BFF response into a flat object. All the \"Whoop puts this data over there, not where you'd expect\" knowledge lives here. Tested against captured fixtures.\n- **`src\u002Ftools\u002Fv2\u002F\u003Ctool>.ts`** — ~25-100 lines. Registers the tool, parses input args, calls the client, runs the projection, validates with zod, returns.\n\nAlmost no logic in the tool file. That's all in the projection — which makes the codebase highly testable (projections are pure transformations, tested against `tests\u002Ffixtures\u002F*.json` without hitting the network).\n\n### Shape drift handling\n\nWhen Whoop changes a response shape, the projection emits unexpected data, zod's `.parse()` fails, and the MCP throws `WhoopProjectionError` instead of silently returning malformed data to Claude. Fix: use `whoop_raw` + `whoop_endpoints` to capture the new shape, update the projection, update the fixture, ship.\n\n> **Recent example:** in May 2026, Whoop migrated recovery + strain deep-dives from `GRAPHING_CARD` tiles (keyed by `content.title` like `\"RECOVERY\"`) to `SCORE_GAUGE` + `CONTRIBUTORS_TILE` items with stable `content.id` keys (`RECOVERY_SCORE_GAUGE`, `CONTRIBUTORS_TILE_HRV`). Other deep-dives still use the old card-based shape. The escape-hatch tools made the migration trivial to debug.\n\n\n---\n\n## The 48 tools\n\nCompact summary. **Full per-tool reference (input shape · source endpoints · output shape · notes) → [`TOOLS.md`](TOOLS.md).** Tools marked ⚠️ are writes (default `confirm: false`, preview-first). Tools marked 🔒 are gated — the catalog tool in the same group must be called once per session before they'll run.\n\n| Group | Tools |\n|---|---|\n| **Snapshots & profile** (4) | `whoop_today` · `whoop_day` · `whoop_profile` · `whoop_calendar` |\n| **Deep dives** (3) | `whoop_recovery` · `whoop_sleep` · `whoop_strain` |\n| **Trends** (2) | `whoop_trend` · `whoop_compare` |\n| **Stress + sleep coach** (2) | `whoop_stress` · `whoop_sleep_need` |\n| **Live** (3) | `whoop_live_hr` · `whoop_live_state` · `whoop_live_stress` |\n| **Activities** (5) | `whoop_workouts` · `whoop_workout` · `whoop_sports_catalog` · `whoop_activity_create` ⚠️🔒 · `whoop_activity_delete` ⚠️ |\n| **Strength reads** (6) | `whoop_lift_prs` · `whoop_lift_exercise` 🔒 · `whoop_lift_progression` 🔒 · `whoop_lift_history` · `whoop_lift_library` · `whoop_lift_catalog` |\n| **Strength writes** (3) | `whoop_lift_log` ⚠️🔒 · `whoop_lift_template_save` ⚠️🔒 · `whoop_lift_custom_exercise` ⚠️🔒 |\n| **Journal** (5) | `whoop_journal` · `whoop_journal_catalog` · `whoop_behavior_impact` · `whoop_journal_log` ⚠️🔒 · `whoop_journal_autopop` ⚠️ |\n| **Women's health** (3) | `whoop_cycle` · `whoop_cycle_log` ⚠️ · `whoop_symptom_log` ⚠️🔒 |\n| **Coach + performance** (2) | `whoop_coach_ask` ⚠️ · `whoop_performance_assessment` |\n| **Smart alarm** (2) | `whoop_smart_alarm` · `whoop_smart_alarm_set` ⚠️ |\n| **Social** (2) | `whoop_leaderboard` · `whoop_communities` |\n| **Settings** (4) | `whoop_hr_zones` · `whoop_hr_zones_set` ⚠️ · `whoop_profile_update` ⚠️ · `whoop_hidden_metric` ⚠️ |\n| **Escape hatch** (2) | `whoop_raw` · `whoop_endpoints` |\n\n**Total: 48** (32 reads + 14 writes + 2 escape hatches). For each tool's input args, source endpoint(s), and output shape, see [`TOOLS.md`](TOOLS.md).\n\n---\n\n## Authentication\n\nWhoop's iOS app uses **AWS Cognito** routed through a Whoop-owned proxy (`\u002Fauth-service\u002Fv3\u002Fwhoop\u002F`). The proxy fills in `ClientId` + `SECRET_HASH` server-side — no IPA extraction needed.\n\n**Bootstrap once** (email + password + SMS MFA code if your account has it on) → tokens written to `.env`. **After that, it's hands-off**: access tokens auto-refresh every 24h via the refresh token; refresh token lives ~30 days. Single-flight refresh gate prevents thundering-herd refreshes when concurrent tool calls all see a stale token at the same time.\n\nAuth requests impersonate the iOS AWS Swift SDK (the proxy 403s a Node-style User-Agent), and data requests carry the **WHOOP iOS app's own identity headers** (`user-agent: iOS`, the `x-whoop-*` device set, a per-install identifier) so the traffic blends with the legitimate app rather than standing out — see [`WHOOP.md` → Headers for data requests](WHOOP.md) for the full set and the reasoning.\n\n**Error classes** (`src\u002Fwhoop\u002Ferrors.ts`):\n\n| Error | When | Behavior |\n|---|---|---|\n| `WhoopAuthExpiredError` | 401 from Whoop | TokenManager refreshes on next call |\n| `WhoopApiError` | 4xx with body | Description surfaced to caller |\n| `WhoopServerError` | 5xx | Transient — retry |\n| `WhoopProjectionError` | Projection output failed zod parse | Whoop changed shape — fix the projection |\n\nWhen refresh-token lifetime expires (~30 days), re-run `whoop-mcp auth`. It auto-detects local vs deployed and, for a deployment, pushes the new tokens to it. Brand-new SMS code (if your account has MFA), fresh 30-day window.\n\n---\n\n## Write-safety harness\n\nEvery write tool defaults `confirm: false`. The first call returns a **preview** of what would execute. Claude must explicitly re-call with `confirm: true` to fire the actual request. Without the gate, a hallucinated \"log my workout\" could create garbage activities on your account.\n\nThe preview shape (lives in `src\u002Fwhoop\u002Fwrite_safety.ts`):\n\n```json\n{\n  \"preview\": true,\n  \"will_execute\": {\n    \"method\": \"POST\",\n    \"path\": \"\u002Fweightlifting-service\u002Fv2\u002Fweightlifting-workout\u002Factivity\",\n    \"body_summary\": {\n      \"exercise_count\": 3, \"set_count\": 12,\n      \"exercise_list\": [{\"name\": \"BENCHPRESS_BARBELL\", \"set_count\": 5}, ...]\n    }\n  },\n  \"set_confirm_true_to_run\": true\n}\n```\n\nClaude reads this back to you, you confirm, Claude re-calls with `confirm: true`, the actual POST fires. Every write tool's output schema is a `withPreview(ReceiptSchema)` discriminated union — preview or receipt, never both.\n\n---\n\n## Bundled catalogs\n\nFour datasets compiled into the MCP at build time (not fetched at runtime):\n\n| Catalog | Entries | Catalog tool | Use |\n|---|---:|---|---|\n| `behaviors.ts` | 308 | `whoop_journal_catalog` | Journal behavior validation |\n| `exercises.ts` | 372 | `whoop_lift_catalog` | Strength Trainer exercises |\n| `sports.ts` | 203 | `whoop_sports_catalog` | `sport_id` ↔ name |\n| `endpoints.ts` | 311 | `whoop_endpoints` | API path search |\n\n**Session-scoped gate**: tools that take IDs from sports\u002Fexercises\u002Fbehaviors refuse to run until the corresponding catalog tool has been called once per session. Keeps ~14k tokens out of the system prompt. AI calling e.g. `whoop_activity_create` first gets `{error: \"Must call whoop_sports_catalog first…\"}`.\n\n---\n\n## Configuration\n\n### Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `WHOOP_EMAIL` | yes | Your Whoop login email |\n| `WHOOP_PASSWORD` | yes (bootstrap only) | Your Whoop login password (used only during bootstrap) |\n| `WHOOP_IOS_BEARER_TOKEN` | yes | Cognito access token (24h, auto-refreshed) |\n| `WHOOP_COGNITO_REFRESH_TOKEN` | yes | Cognito refresh token (~30d) |\n| `WHOOP_USER_ID` | no | Your Whoop user ID — used by `whoop_profile`, `whoop_leaderboard`. Avoids one bootstrap call per session. |\n| `WHOOP_TIMEZONE` | no | IANA timezone (e.g., `America\u002FLos_Angeles`). If unset, auto-detected from your Whoop profile and refreshed hourly. Set explicitly to override. |\n| `WHOOP_INSTALLATION_ID` | no (auto) | The per-install device identifier sent as `x-whoop-installation-identifier`. Generated once and written to `.env` on first run — don't set it by hand. |\n| `WHOOP_TOKEN_STORE` | no | `envfile` (default — persists refreshed tokens back to `.env`) or `memory` (for read-only filesystems; re-bootstrap every ~30 days). |\n\n### Claude Desktop config\n\n```json\n{\n  \"mcpServers\": {\n    \"whoop\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fnode\",\n      \"args\": [\"\u002Fabsolute\u002Fpath\u002Fto\u002Fwhoop-mcp\u002Fdist\u002Fserver.js\"]\n    }\n  }\n}\n```\n\nThe MCP loads `.env` from the repo root (relative to `server.js`). Use absolute paths — Claude Desktop doesn't inherit shell `PATH`.\n\n---\n\n## Remote hosting\n\nThe MCP also speaks HTTP — deploy once, use from multiple devices. Same 48 tools, same auto-refresh, behind a bearer-token gate at a URL.\n\n```bash\n# 1. Local bootstrap (Cognito needs an interactive MFA prompt)\nwhoop-mcp auth\n\n# 2. Build + deploy via the shipped Dockerfile (Fly\u002FRailway\u002FRender\u002FVPS — all work)\ndocker build -t whoop-mcp .\n\n# 3. Run with env: WHOOP_EMAIL, WHOOP_IOS_BEARER_TOKEN, WHOOP_COGNITO_REFRESH_TOKEN,\n#    MCP_TRANSPORT=http, MCP_AUTH_TOKEN=$(openssl rand -hex 32)\n```\n\n**Claude Desktop** doesn't natively speak remote MCP — bridge through stdio with [`mcp-remote`](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fmcp-remote):\n\n```json\n{ \"mcpServers\": { \"whoop\": {\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"mcp-remote\", \"https:\u002F\u002Fyour-app.fly.dev\u002Fmcp\",\n           \"--header\", \"Authorization:Bearer your-mcp-auth-token\"]\n}}}\n```\n\n**Claude Code** speaks remote MCP natively: `claude mcp add whoop --url ... --header ...`.\n\n**claude.ai web + Claude mobile app** can't use a bearer token — their custom-connector UI only supports OAuth. The server includes an OAuth 2.1 + PKCE authorization server for exactly this. Enable it by setting two extra env vars:\n\n```bash\nAUTH_PASSWORD=\u003Ca password you'll type once when adding the connector>\nPUBLIC_URL=https:\u002F\u002Fyour-app.fly.dev   # your server's public origin (the OAuth issuer)\n```\n\nThen in Claude: **Settings → Connectors → Add custom connector**, paste `https:\u002F\u002Fyour-app.fly.dev\u002Fmcp`, and Claude walks the OAuth flow. It pops a small password page (served by your server) — enter `AUTH_PASSWORD`, approve, done. The connector then syncs across every device logged into your Claude account (web, desktop, mobile). The password gate means a stranger who finds your URL still can't connect without it. `MCP_AUTH_TOKEN` doubles as the JWT signing secret; leave `AUTH_PASSWORD` unset to disable this path.\n\nAll of the above is what `whoop-mcp cloud` automates for you — the manual steps here are for reference or hand-rolling.\n\n**When Cognito expires (~30 days)**: `whoop-mcp auth` from your Mac. Silent if your account has no SMS MFA; prompts for the code if it does. Auto-detects your deployment and pushes the new tokens to it (Fly\u002FRailway\u002FCloud Run\u002Fcustom), ~10s restart. Requires being at a machine with the repo + the platform CLI.\n\n**Security**: bearer-token and OAuth paths both gate `\u002Fmcp`. Generate the token random (`openssl rand -hex 32`), HTTPS only, never commit, rotate if leaked. OAuth access\u002Frefresh tokens are stateless signed JWTs (survive restarts); auth codes are one-time + 60s-lived; PKCE S256 is enforced. `\u002Fhealth` is the only path without auth.\n\n---\n\n## The `whoop-mcp` CLI\n\n`whoop-mcp` is the single entry point for everything — there are no `npm run` scripts. It works from any directory (it resolves its own install path), so `whoop-mcp deploy` from `~\u002FDesktop` does the same thing as `cd whoop-mcp && fly deploy`.\n\n```bash\n# One-time, after cloning:\nnpm install && npx tsc && npm link   # the only npm steps; `npx tsc` does the first build\n\nwhoop-mcp       # banner + full command list\n```\n\nCommands by group:\n\n| Group | Commands |\n|---|---|\n| **Get started** | `cloud` ★ (guided server deploy + Claude connect) · `local` (guided local setup) |\n| **Setup** | `auth` (log in + save tokens — re-run to re-auth; auto-detects local vs deployed and pushes new tokens to your deployment) |\n| **Deployed** | `deploy` · `logs` · `status` · `ping` |\n| **Local dev** | `start [--http]` · `dev` · `dev:http` · `build` · `test` · `typecheck` |\n| **Inspect** | `info` · `tools` · `config \u003Cstdio\\|http>` |\n| **Help** | `help` · `version` (+ `--help`, `-v` aliases) |\n\nMost people only ever need the two **Get started** commands plus `auth` (to re-auth when tokens expire). The rest are for power users — `whoop-mcp ping` (\"is my deploy alive\"), `whoop-mcp logs`, `whoop-mcp start` (drop-in for `node dist\u002Fserver.js`), etc.\n\n---\n\n## Privacy + security\n\n- **Credentials live in `.env` on your machine.** Email, password, access token, refresh token — never leave your filesystem. Claude can't read them (it doesn't have filesystem access unless you wire in a filesystem MCP).\n- **The only outbound traffic is HTTPS to `api.prod.whoop.com`.** No telemetry, no analytics, no third-party servers. The MCP is open source — every line that touches your data is auditable.\n- **Write safety**: every write tool defaults to `confirm: false`. The preview shape includes what would be sent. You see it in chat before any mutation. To go further, remove specific writes from `src\u002Ftools\u002Fregister.ts` or use Claude Desktop's \"always require approval\" setting.\n- **Hardened in 1.2.3**: token files are written `0600`, your account password is wiped from `.env` after login, OAuth tokens are audience-bound and signed with a key derived from `MCP_AUTH_TOKEN`, the HTTP server sends anti-clickjacking + CSP headers, the connector-password gate has a global brute-force ceiling, and deploy secrets are pushed over stdin (not argv). Full detail in [`SECURITY.md`](SECURITY.md) and [`CHANGELOG.md`](CHANGELOG.md).\n\n---\n\n## Troubleshooting\n\n**\"AUTH FAIL: Cognito InitiateAuth failed (400)\"**\n> Wrong email or password. Double-check `.env`.\n\n**\"AUTH FAIL: Cognito MFA challenge missing Session token\"**\n> The InitiateAuth response was malformed (unusual). Re-run `whoop-mcp auth` — Cognito occasionally drops sessions.\n\n**\"MFA verification did not return tokens\"**\n> You entered the wrong SMS code (or it timed out). Codes expire after ~3 minutes.\n\n**\"WhoopAuthExpiredError\" after every call**\n> Your refresh token has expired (>30 days since last login). Re-run `whoop-mcp auth` — it logs you back in, saves the tokens locally, and (if you deployed) auto-detects your host and pushes the new tokens to it in one step. If your account has MFA you'll get a fresh SMS code on your phone to type in the terminal.\n\n**\"WhoopServerError: 502\" \u002F \"503\" \u002F \"504\"**\n> Whoop's servers are having issues. Retry in 30 seconds.\n\n**Claude says it doesn't see any whoop tools**\n> Check `claude_desktop_config.json` paths are absolute. Restart Claude Desktop fully (quit, then reopen).\n> Check the MCP server runs without errors: `whoop-mcp dev` — it should start silently and wait on stdin.\n\n**\"WhoopApiError: 422 on \u002Fprofile-service\u002Fv1\u002Fprofile\"**\n> Your `whoop_profile_update` body is too partial. Send most fields (gender from {MALE,FEMALE,NON_BINARY} only, birthday as YYYY-MM-DD or ISO datetime, country ISO-2). If `country=US`, also send `state` — Whoop returns 400 `\"AdminDivision (state) must be set for US\"` otherwise.\n\n**\"Whoop API error 409 on \u002Fweightlifting-service\u002Fv2\u002Fweightlifting-workout\u002Factivity\"**\n> Time window conflicts with an existing workout. Use a different range.\n\n**\"WhoopProjectionError for whoop_X\"**\n> Whoop changed a response shape. Capture the new response (e.g. via `whoop_raw`), inspect, update the projection.\n\n**Tests fail after `git pull`**\n> Pull may have updated captured fixtures. Run `whoop-mcp test` again to see what changed. If projections need updating, that's the work.\n\n**`whoop-mcp build` (or `npx tsc`) fails with \"Top-level await is currently not supported with the 'cjs' output format\"**\n> You're using an old Node. Upgrade to Node 24+.\n\n**\"Error: ENOENT: no such file or directory, open '.env'\"**\n> Create `.env` at the repo root (or wherever `dist\u002Fserver.js` is being run from — the MCP loads `.env` relative to the entry).\n\n**\"Cannot find module '@modelcontextprotocol\u002Fsdk\u002Fserver\u002Fmcp.js'\"**\n> Run `npm install`.\n\n**\"AbortError: This operation was aborted\"**\n> A request to Whoop's API took longer than 30s. Either Whoop is slow or your network is slow. Retry.\n\n---\n\n## Comparison to alternatives\n\n| Approach | Pros | Cons |\n|---|---|---|\n| **This MCP** | Full iOS API surface (48 total: 32 reads + 14 writes + 2 escape hatches), writes supported, structured outputs, auto-refresh, write-safety, session-scoped catalog gate | Unsupported by Whoop (see [FAQ](#faq) for what that means); reverse-engineered (Whoop could break it at any time); local install required |\n| Whoop's public OAuth API | Official, supported, 6 webhook events, scoped permissions | Only 13 endpoints; read-only; no journal\u002Fstrength\u002Fstress\u002Fcoach\u002Fsmart-alarm\u002Ftrends\u002Fhypnogram; numeric `sport_id` removed 2025-09-01; 429s exist |\n| HealthKit-based scraper | Bypass Whoop entirely; uses Apple's data sync | Loses Whoop-specific data (recovery score, journal, coach); requires iOS device involvement |\n| Direct mitmproxy capture | See everything | Manual, not programmable, doesn't scale |\n| Whoop iOS app + screenshots → Claude | Works without code | Painful, slow, no writes |\n\nThis MCP is the only option for **programmatic write access** to your Whoop data right now.\n\n---\n\n## FAQ\n\n**Q: Is this supported by Whoop?**\nA: No. This MCP works through Whoop's private iOS API, which isn't a public surface they intend for third-party tools. Whoop's terms reserve the right to take action against accounts they catch using unsupported integrations — realistically that means suspending API access or terminating the membership. The author has used the MCP heavily for weeks without issue, and traffic patterns look similar to normal app usage, but there's no guarantee. If losing your Whoop account would be a problem for you, don't use this.\n\n**Q: Why not use Whoop's public OAuth API instead?**\nA: It's 13 endpoints, all read-only, no journal, no strength, no stress, no coach, no smart alarm, no trends beyond a single recovery score per day. Whoop also pulled numeric `sport_id` past 2025-09-01 (now `sport_name` strings only). If you only need recovery score + sleep stage totals + workout list, the OAuth API is the right answer.\n\n**Q: Will this work with the Whoop 4.0 vs 5.0 strap?**\nA: Yes — the API doesn't care which strap you have. It cares about your account.\n\n**Q: What about Whoop 6.0?**\nA: When it launches and the iOS app updates, the api version may bump from 7 to 8. The MCP's `constants.ts` may need an update. Worst case, projections break and you fix them.\n\n**Q: Can I run this on a server \u002F cloud \u002F always-on?**\nA: Sure. The MCP doesn't care where it runs. Just make sure your `.env` survives restarts.\n\n**Q: Can I share this MCP with my friends?**\nA: Each user needs their own `.env` with their own Whoop credentials. Don't share tokens.\n\n**Q: Is there an HTTP transport instead of stdio?**\nA: Yes — set `MCP_TRANSPORT=http` to expose the MCP over Streamable HTTP behind a bearer-token + OAuth 2.1 gate (since v1.1.0). See [Remote hosting](#remote-hosting). stdio stays the default for local Claude Desktop \u002F Claude Code.\n\n**Q: Does this support Claude's Computer Use API?**\nA: It's MCP-compatible — anything that speaks MCP can talk to it.\n\n**Q: Why TypeScript instead of Python?**\nA: The MCP SDK is most mature in TypeScript. Also Whoop's API responses are heavily nested — zod is genuinely the best validation library for that shape work.\n\n**Q: Why Node 24 specifically?**\nA: Uses `import.meta.dirname` (added in 20.11), modern `fetch`, native ESM, `AbortController`. Node 18 might work; 16 won't.\n\n**Q: How long did this take?**\nA: ~3 weeks of evening\u002Fweekend work for v1, plus another week to rewrite as v2 with proper projections and the write-safety harness.\n\n**Q: Will you maintain this?**\nA: Best-effort. PRs welcome.\n\n---\n\n## Disclaimers\n\n- **Not affiliated with Whoop.** \"WHOOP\" is a trademark of WHOOP, Inc. Community-built tool that interacts with surfaces Whoop has not published. See the [FAQ](#faq) for the practical implications.\n- **No warranty, use at your own discretion.** The API surface is reverse-engineered — Whoop can change response shapes at any time. The zod schemas surface drift as `WhoopProjectionError` instead of silent corruption.\n- **Respect rate limits.** Single-digit RPS in normal use. Don't be the person who triggers a backend alert that gets every user of this MCP banned.\n- **Don't share tokens.** Your `.env` is yours. Don't commit it, don't paste it anywhere.\n\n---\n\n## Acknowledgments\n\n- **WHOOP** for building a fitness platform worth reverse-engineering\n- **Anthropic** for [MCP](https:\u002F\u002Fmodelcontextprotocol.io) and [Claude](https:\u002F\u002Fclaude.ai)\n- **mitmproxy** for being the tool that made discovery possible\n- **The TypeScript + zod community** for making strict validation pleasant\n- The various API consumers + bloggers who documented bits of Whoop's private API over the years\n\nThis is open source under the terms in `LICENSE`. Contributions welcome.\n","whoop-mcp 是一个 Model Context Protocol 服务器，通过反向工程的 Whoop iOS 私有 API，为 Claude 或任何 MCP 客户端提供对 Whoop 健身数据的完全读写访问权限。该项目提供了 48 个工具，涵盖恢复、睡眠、压力、HRV 趋势、力量训练、日记、Whoop 教练和智能闹钟等功能。使用 TypeScript 和 zod 构建，支持自动刷新 Cognito 认证。适合需要将健身数据与 AI 系统集成以进行高级分析或个性化建议的场景，如个人健康管理、运动表现优化等。请注意，此项目利用的是 Whoop 的私有 API，不符合 Whoop 的服务条款。","2026-06-06 04:10:56","CREATED_QUERY"]