totem

<p align="center">
  <img src="assets/banner.svg" alt="totem — 48 tools, 47 microservices, 311 endpoints" width="820">
</p>

<p align="center">
  <i><b>Totem</b> gives Claude (or any MCP-compatible AI) <b>full read + write access to your wearable data.</b> Today it speaks <b>Whoop</b> — every metric, through Whoop's private iOS API.</i>
</p>

<p align="center">
  <a href="#remote-hosting"><img src="https://img.shields.io/badge/Claude_Code-a855f7?style=for-the-badge" alt="Claude Code"></a>
  <a href="#claude-desktop-config"><img src="https://img.shields.io/badge/Claude_Desktop-7c3aed?style=for-the-badge" alt="Claude Desktop"></a>
  <img src="https://img.shields.io/badge/ChatGPT_Desktop-10a37f?style=for-the-badge" alt="ChatGPT Desktop">
  <img src="https://img.shields.io/badge/Codex-000000?style=for-the-badge" alt="Codex">
  <img src="https://img.shields.io/badge/Gemini_CLI-4285f4?style=for-the-badge" alt="Gemini CLI">
  <img src="https://img.shields.io/badge/Any_MCP_1.x_Client-262626?style=for-the-badge" alt="any MCP 1.x client">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/tools-48-9ca3af?style=flat-square" alt="tools">
  <img src="https://img.shields.io/badge/TypeScript-6.0-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="typescript">
  <img src="https://img.shields.io/badge/Node-24%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="node">
  <img src="https://img.shields.io/badge/MCP-1.x%2B-9ca3af?style=flat-square" alt="mcp">
  <img src="https://img.shields.io/badge/deploy-Fly%20%7C%20Docker%20%7C%20Railway-9ca3af?style=flat-square" alt="deploy">
</p>

<p align="center">
  <video src="https://github.com/user-attachments/assets/b0101d7d-24ad-4341-a88c-dc6fae075f6e" controls muted width="820"></video>
</p>
<p align="center">
  <sub>▶ 2-min demo — the full <code>totem cloud</code> flow: install → Whoop login → Fly deploy → Claude connector → first query.</sub>
</p>

48 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, 233 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](CONTRIBUTING.md)). 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](#faq) if you want the full picture before installing.*

---

## Table of contents

1. [Get Started](#get-started)
2. [Why this exists](#why-this-exists)
3. [What it does](#what-it-does)
4. [Architecture](#architecture)
5. [The 48 tools](#the-48-tools)
6. [Authentication](#authentication)
7. [Write-safety harness](#write-safety-harness)
8. [Bundled catalogs](#bundled-catalogs)
9. [Configuration](#configuration)
10. [Remote hosting](#remote-hosting)
    - [Deploying to Hugging Face Spaces (free hosting)](#deploying-to-hugging-face-spaces-free-hosting)
11. [The `totem` CLI](#the-totem-cli)
12. [Privacy + security](#privacy--security)
13. [Troubleshooting](#troubleshooting)
14. [Comparison to alternatives](#comparison-to-alternatives)
15. [FAQ](#faq)
16. [Disclaimers](#disclaimers)
17. [Acknowledgments](#acknowledgments)

**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)

---

## Get Started

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

```bash
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.

```bash
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.

```bash
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:

```bash
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](#the-totem-cli), [Remote hosting](#remote-hosting), and [Configuration](#configuration). Stuck? See [Troubleshooting](#troubleshooting).

---

## Why this exists

Whoop ships two APIs:

- The **public developer API** at [`developer.whoop.com`](https://developer.whoop.com/api/) 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

| Capability | Tool |
|---|---|
| HRV / RHR / respiratory / VO2 / weight time-series (25 metrics × up to 4 windows) | `whoop_trend` |
| Hypnogram (per-stage sleep timeline) + full stage breakdown (ms + %) + in-sleep HR | `whoop_sleep` |
| Strength Trainer — every set, every workout, full 372-exercise catalog, PRs | `whoop_lift_*` (8 tools) |
| 308-behavior Journal + behavior impact analysis | `whoop_journal*` (5 tools) |
| Stress monitor (intraday timeline) | `whoop_stress, whoop_live_stress` |
| Whoop Coach AI chat | `whoop_coach_ask` |
| Smart Alarm (read + 4 write modes) | `whoop_smart_alarm*` |
| HR zones (read + configure max HR / 5 custom zones) | `whoop_hr_zones*` |
| Compare-windows, sleep coach, calendar grid, performance assessment | `whoop_compare`, `whoop_sleep_need`, `whoop_calendar`, `whoop_performance_assessment` |
| Live HR / activity state / live stress | `whoop_live_*` (3 tools) |
| Community leaderboards, hidden metrics, women's health (cycle / symptoms / MCI) | `whoop_leaderboard`, `whoop_hidden_metric`, `whoop_cycle*` |
| **14 write tools** — log workouts, journal entries, profile edits, smart-alarm config | various |

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