MCP工具

2. Build + deploy via the shipped Dockerfile (Fly/Railway/Render/VPS — all work)

docker build -t whoop-mcp .

Configuration

Environment variables

Claude Desktop config

{
  "mcpServers": {
    "whoop": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/absolute/path/to/whoop-mcp/dist/server.js"]
    }
  }
}

The MCP loads .env from the repo root (relative to server.js). Use absolute paths — Claude Desktop doesn't inherit shell PATH.

---

3. Run with env: WHOOP_EMAIL, WHOOP_IOS_BEARER_TOKEN, WHOOP_COGNITO_REFRESH_TOKEN,

What the iOS API has that the public OAuth doesn't

If 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.

---

Comparison to alternatives

This MCP is the only option for programmatic write access to your Whoop data right now.

---

Troubleshooting

"AUTH FAIL: Cognito InitiateAuth failed (400)" > Wrong email or password. Double-check .env.

"AUTH FAIL: Cognito MFA challenge missing Session token" > The InitiateAuth response was malformed (unusual). Re-run whoop-mcp auth — Cognito occasionally drops sessions.

"MFA verification did not return tokens" > You entered the wrong SMS code (or it timed out). Codes expire after ~3 minutes.

"WhoopAuthExpiredError" after every call > Your refresh token has expired (>30 days since last bootstrap). For a local install, re-run whoop-mcp auth. For a deployed install (Fly etc.), run whoop-mcp refresh from your Mac — it re-bootstraps locally AND pushes the new tokens to your deployed app's secrets in one step. Either way you'll get a fresh SMS code on your phone that you type in the terminal.

"WhoopServerError: 502" / "503" / "504" > Whoop's servers are having issues. Retry in 30 seconds.

Claude says it doesn't see any whoop tools > Check claude_desktop_config.json paths are absolute. Restart Claude Desktop fully (quit, then reopen). > Check the MCP server runs without errors: whoop-mcp dev — it should start silently and wait on stdin.

"WhoopApiError: 422 on /profile-service/v1/profile" > 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.

"Whoop API error 409 on /weightlifting-service/v2/weightlifting-workout/activity" > Time window conflicts with an existing workout. Use a different range.

"WhoopProjectionError for whoop_X" > Whoop changed a response shape. Capture the new response (e.g. via whoop_raw), inspect, update the projection.

Tests fail after git pull > Pull may have updated captured fixtures. Run whoop-mcp test again to see what changed. If projections need updating, that's the work.

whoop-mcp build (or npx tsc) fails with "Top-level await is currently not supported with the 'cjs' output format" > You're using an old Node. Upgrade to Node 24+.

"Error: ENOENT: no such file or directory, open '.env'" > Create .env at the repo root (or wherever dist/server.js is being run from — the MCP loads .env relative to the entry).

"Cannot find module '@modelcontextprotocol/sdk/server/mcp.js'" > Run npm install.

"AbortError: This operation was aborted" > A request to Whoop's API took longer than 30s. Either Whoop is slow or your network is slow. Retry.

---

FAQ

Q: Is this supported by Whoop? A: 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.

Q: Why not use Whoop's public OAuth API instead? A: 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.

Q: Will this work with the Whoop 4.0 vs 5.0 strap? A: Yes — the API doesn't care which strap you have. It cares about your account.

Q: What about Whoop 6.0? A: 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.

Q: Can I run this on a server / cloud / always-on? A: Sure. The MCP doesn't care where it runs. Just make sure your .env survives restarts.

Q: Can I share this MCP with my friends? A: Each user needs their own .env with their own Whoop credentials. Don't share tokens.

Q: Is there an HTTP transport instead of stdio? A: Not yet. The MCP SDK supports SSE but we haven't wired it. PR welcome.

Q: Does this support Claude's Computer Use API? A: It's MCP-compatible — anything that speaks MCP can talk to it.

Q: Why TypeScript instead of Python? A: 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.

Q: Why Node 24 specifically? A: Uses import.meta.dirname (added in 20.11), modern fetch, native ESM, AbortController. Node 18 might work; 16 won't.

Q: How long did this take? A: ~3 weeks of evening/weekend work for v1, plus another week to rewrite as v2 with proper projections and the write-safety harness.

Q: Will you maintain this? A: Best-effort. PRs welcome.

---