Totem

Totem gives Claude (or any MCP-compatible AI) full read + write access to your wearable data. Today it speaks Whoop — every metric, through Whoop's private iOS API.

_{▶ 2-min demo — the full totem cloud flow: install → Whoop login → Fly deploy → Claude connector → first query.}

55 tools, structured zod-validated outputs, bundled catalogs (372 exercises, 308 behaviors, 203 sports, 311 endpoints), write-safety harness, automatic Cognito token refresh, bounded in-memory read cache. TypeScript 6, Node 24, 278 tests.

Totem is becoming a universal wearables bridge. Whoop is the first adapter — every metric, fully wired. Fitbit, Apple Watch, and Garmin are in progress (contributors welcome). The MCP + projection layer is device-agnostic; an adapter just maps its source into the same shared schemas, so everything below applies to whatever you wear.

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 if you want the full picture before installing.

Table of contents

1. Get Started
2. Why this exists
3. What it does
4. Architecture
5. The 55 tools
6. Authentication
7. Write-safety harness
8. Bundled catalogs
9. Configuration
10. Remote hosting
    • Deploying to Hugging Face Spaces (free hosting)
11. The totem CLI
12. Privacy + security
13. Troubleshooting
14. Comparison to alternatives
15. FAQ
16. Disclaimers
17. Acknowledgments

Other root-level docs: TOOLS.md (full per-tool reference) · WHOOP.md (full API reference) · CHANGELOG.md · CONTRIBUTING.md · SECURITY.md · LICENSE

Get Started

Prerequisites: Node 24+ and a Whoop account (any membership tier).

git clone https://github.com/thebriangao/totem.git
cd totem && npm install && npx tsc && npm link

That puts totem on your PATH (the one-time npx tsc builds it; after that every workflow is a totem 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:

★ Recommended — totem cloud

Deploys 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:

1. Whoop login — email + password, plus the SMS code if your account has MFA. Tokens are saved locally and pushed to the host.
2. Pick a host — Fly (automated + tested), Railway, Google Cloud Run, or your own server (guided Docker steps).
3. Secrets — generates MCP_AUTH_TOKEN and asks you to choose a connector password.
4. Deploy + verify — sets env, deploys, confirms /health and the OAuth endpoints are live.
5. Connect — prints ready-to-paste setup for claude.ai, ChatGPT, Claude Code (remote), and Cursor / Windsurf / any HTTP MCP client (URL + password for the OAuth connectors, a bearer-token block for the rest), and opens claude.ai's connector page.

totem cloud

Local only — totem local

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

totem local

Keeping it alive

Whoop'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:

totem auth

Silent if your account has no SMS MFA; prompts for the code if it does. Pushes fresh tokens to your deployment automatically.

Check it works

Ask Claude: "how am I doing today on whoop?" — you should get structured recovery / sleep / strain back.

Prefer to wire everything up by hand? The guided commands just automate the steps documented in The totem CLI, Remote hosting, and Configuration. Stuck? See Troubleshooting.

Why this exists

Whoop ships two APIs:

• The public developer API at developer.whoop.com 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/RHR 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.
• 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.

This MCP wraps the iOS surface.

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.

What it does

The MCP runs as a local Node process. It speaks Model Context Protocol over stdio (or HTTP for remote deployments), registers 55 tools at startup, and waits for tool calls from a connected MCP client.

When a tool is called:

1. Authenticates via the cached Cognito access token (auto-refreshes if expired)
2. Issues HTTP requests to api.prod.whoop.com
3. Walks the response to extract a flat domain object (the projection step)
4. Validates the projected object against a zod schema (catches Whoop API drift)
5. Returns the structured JSON to the MCP client

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

See The 55 tools for the full per-tool reference.

Architecture