general MCP Server
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.
Discovered via github-seeds:mcp-new and last synced 2mo ago.
1. Install the package
npx @thebriangao/totem
2. Add to claude_desktop_config.json
{
"mcpServers": {
"-thebriangao-totem": {
"command": "npx",
"args": [
"@thebriangao/totem"
]
}
}
}Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
Tool
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`](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 48 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 48 tools](#the-48-tools) for the full per-tool reference. --- ## Architecture ``` Claude Desktop / Code ──stdio──▶ src/server.ts ──▶ 48 tool handlers │ ┌──────────────────┼──────────────────┐ ▼ ▼ ▼ schemas (zod) projections (raw→flat) whoop/client │ ▼ HTTPS api.prod.whoop.com ``` ### Three layers per tool Every tool is a schema + projection + handler: - **`src/schemas/<tool>.ts`** — zod schema. The contract Claude sees. Used at runtime to validate the projection's output before returning. - **`src/projections/<tool>.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. - **`src/tools/v2/<tool>.ts`** — ~25-100 lines. Registers the tool, parses input args, calls the client, runs the projection, validates with zod, returns. Almost 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/fixtures/*.json` without hitting the network). ### Shape drift handling When 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. > **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. --- ## The 48 tools Compact 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.
When
4xx with body
5xx
Projection output failed zod parse
Entries
`whoop_journal_catalog`
`whoop_lift_catalog`
`whoop_sports_catalog`
`whoop_endpoints`
Required
Your Whoop account email
yes (bootstrap only)
From `totem auth` on your local machine (written to `.env`)
From `totem auth` on your local machine (written to `.env`)
From `.env` after running `totem auth`
no
no (auto)
no
Generate one with `openssl rand -hex 32` (or reuse the value from `.env.deploy` if you ran a deploy flow)
A password you'll type once when adding the Claude connector
Your Space's public URL — e.g. `https://<your-hf-username>-<your-space-name>.hf.space`
`7860` — HuggingFace's required port. Without this the container listens on 3000 and is unreachable.
Commands
Pros
401 from Whoop
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and proc
When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search
When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch.
When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms, or wants to do social listening and engagement triage. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' 'grow my following,' 'Tik
DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.
The first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.
AI PDF chatbot agent built with LangChain & LangGraph
High-performance AI pipeline engine with a C++ core and 50+ Python-extensible nodes. Build, debug, and scale LLM workflows with 13+ model providers, 8+ vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.
Learn how to use the UGC Claude skill. Complete guide with installation instructions and examples.
Learn how to use the AI README Manager Claude skill. Complete guide with installation instructions and examples.
Learn how to use the Security Operator Claude skill. Complete guide with installation instructions and examples.