Totem

Name: Totem
Author: briangaoo

by briangaooversion 1.4.3i★ –iRuns on your computer

Registry nameio.github.briangaoo/totem

Install

Overview

Description from the maker (original English)

Totem — talk to your wearables with AI. Today: full Whoop access (48 tools).

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiVery new★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Other
You need to fill in: WHOOP_IOS_BEARER_TOKEN, WHOOP_COGNITO_REFRESH_TOKEN, WHOOP_EMAIL

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: WHOOP_IOS_BEARER_TOKEN, WHOOP_COGNITO_REFRESH_TOKEN, WHOOP_EMAIL, WHOOP_USER_ID, WHOOP_TIMEZONE

Values marked secret are keys to your account. Never share them or paste them into a chat.

You need

npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "totem": {
      "command": "npx",
      "args": [
        "-y",
        "@briangaoo/totem"
      ],
      "env": {
        "WHOOP_IOS_BEARER_TOKEN": "your-value",
        "WHOOP_COGNITO_REFRESH_TOKEN": "your-value",
        "WHOOP_EMAIL": "your-value",
        "WHOOP_USER_ID": "your-value",
        "WHOOP_TIMEZONE": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add totem --env WHOOP_IOS_BEARER_TOKEN=your-value --env WHOOP_COGNITO_REFRESH_TOKEN=your-value --env WHOOP_EMAIL=your-value --env WHOOP_USER_ID=your-value --env WHOOP_TIMEZONE=your-value -- npx -y @briangaoo/totem

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "totem": {
      "command": "npx",
      "args": [
        "-y",
        "@briangaoo/totem"
      ],
      "env": {
        "WHOOP_IOS_BEARER_TOKEN": "your-value",
        "WHOOP_COGNITO_REFRESH_TOKEN": "your-value",
        "WHOOP_EMAIL": "your-value",
        "WHOOP_USER_ID": "your-value",
        "WHOOP_TIMEZONE": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "totem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@briangaoo/totem"
      ],
      "env": {
        "WHOOP_IOS_BEARER_TOKEN": "your-value",
        "WHOOP_COGNITO_REFRESH_TOKEN": "your-value",
        "WHOOP_EMAIL": "your-value",
        "WHOOP_USER_ID": "your-value",
        "WHOOP_TIMEZONE": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

WHOOP_IOS_BEARER_TOKEN secret required env
Whoop Cognito access token. Obtain via `totem auth` from the repo, which prompts for your Whoop email + password + SMS MFA code, then writes both tokens to a local .env. Auto-refreshes every ~24h.
WHOOP_COGNITO_REFRESH_TOKEN secret required env
Whoop Cognito refresh token (~30 day lifetime). Obtained alongside the bearer token from `totem auth`. When this expires, run `totem auth` to get a fresh pair.
WHOOP_EMAIL required env
Your Whoop account email. Used only by `totem auth` — the running server reads tokens, not credentials.
WHOOP_USER_ID env
Your numeric Whoop user ID. Optional — used by whoop_profile and whoop_leaderboard. Avoids one redundant bootstrap call per session if set.
WHOOP_TIMEZONE env
IANA timezone (e.g., America/Los_Angeles) for response timestamps. Optional — if unset, the server auto-detects from your Whoop profile's timezone_offset field (refreshed hourly).

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 8, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account briangaoo, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Otheri

More stars than 0% of the other 18499 servers in this category
Published to the registry more recently than 10% of the other 18499 servers in this category
Basic checks equal to or better than 100% of the other 18499 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Totem safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: WHOOP_IOS_BEARER_TOKEN, WHOOP_COGNITO_REFRESH_TOKEN, WHOOP_EMAIL

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (1.4.3) reached the registry 5 months ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: Spec Driven Development, Remote Desktop Commander, SolveHub

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Spec Driven Development

MCP Server that facilitates spec-driven development workflows, not just Vibe Coding.

by formulahendryEarly↓ 66/wk★ 440Updated 14 months ago

Runs on your computer

Install

Remote Desktop Commander

Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.

by desktop-commanderGrowing★ 211Updated 3 days ago

Runs in the cloud✓ desktopcommander.app

Install

SolveHub

CAPTCHA and anti-bot solving for Turnstile, DataDome, Akamai, PerimeterX and Imperva.

by seencxyVery newUpdated today

Runs on your computer

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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

Get Started
Why this exists
What it does
Architecture
The 55 tools
Authentication
Write-safety harness
Bundled catalogs
Configuration
Remote hosting

Deploying to Hugging Face Spaces (free hosting)

The totem CLI
Privacy + security
Troubleshooting
Comparison to alternatives
FAQ
Disclaimers
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:

Whoop login — email + password, plus the SMS code if your account has MFA. Tokens are saved locally and pushed to the host.
Pick a host — Fly (automated + tested), Railway, Google Cloud Run, or your own server (guided Docker steps).
Secrets — generates MCP_AUTH_TOKEN and asks you to choose a connector password.
Deploy + verify — sets env, deploys, confirms /health and the OAuth endpoints are live.
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

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*`
15 write tools — log workouts, journal entries, profile edits, smart-alarm config, edit sleep times	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.

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:

Authenticates via the cached Cognito access token (auto-refreshes if expired)
Issues HTTP requests to api.prod.whoop.com
Walks the response to extract a flat domain object (the projection step)
Validates the projected object against a zod schema (catches Whoop API drift)
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

Claude Desktop / Code  ──stdio──▶  src/server.ts  ──▶  49 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/ .ts` — zod schema. The contract Claude sees. Used at runtime to validate the projection's output before returning.
`src/projections/ .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/ .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 55 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 compact/aggregate reads that fold several source calls into one lower-token response; whoop_weekly_plan is ⚡ experimental (its endpoint shape hasn't been verified

Only the beginning is shown; read the rest in the repo

Totem

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Otheri

Common questions

Alternatives

Spec Driven Development

Remote Desktop Commander

SolveHub

README from the maker

Table of contents

Get Started

★ Recommended — totem cloud

Local only — totem local

Keeping it alive

Check it works

Why this exists

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

What it does

Architecture

Three layers per tool

Shape drift handling

The 55 tools

★ Recommended — `totem cloud`

Local only — `totem local`