Totem

What totem MCP server does

totem provides an MCP interface to Whoop wearable data. It currently supports Whoop as its device adapter and exposes 55 tools covering recovery, sleep, strain, heart-rate metrics, respiratory data, VO2, weight trends, workouts, Strength Trainer records, journal entries, stress, cycle information, leaderboards, and Whoop Coach conversations.

The tool set also includes write operations. Depending on the operation, an agent can log workouts, add journal entries, edit profile information, configure Smart Alarm settings, adjust heart-rate zones, or change recorded sleep times. These actions are covered by a write-safety harness rather than being limited to read-only queries.

This is intended for workflows that need more than the public Whoop OAuth API provides. The project states that its private API exposes data such as hypnograms, detailed sleep stages, behavior impacts, live stress, and additional trend metrics that are not available through the public surface.

How it works

The totem MCP server runs as a TypeScript and Node process. In local mode, it communicates with an MCP client over stdio. A remote deployment can expose the service over HTTP for clients that connect to hosted MCP servers.

At startup, the process registers its tools and validates inputs and outputs with structured schemas. For a request, it uses a cached Whoop Cognito access token, refreshes that token when needed, sends HTTP requests to Whoop’s production API, and projects the returned response into a flatter domain object for the client. Read results use a bounded in-memory cache.

The project includes bundled reference catalogs for 372 exercises, 308 journal behaviors, 203 sports, and 311 API endpoints. It is written in TypeScript, targets Node 24 or later, and includes automated tests according to the repository documentation.

Setup and configuration

Run the totem MCP server locally after installing Node 24+, cloning the repository, installing dependencies, compiling the TypeScript source, and linking the command-line package. The guided totem local command walks through Whoop authentication and can write configuration for supported clients including Claude Desktop, Claude Code, Cursor, VS Code with Copilot, Gemini CLI, Codex CLI, and Windsurf.

The totem cloud command guides remote deployment to Fly, Railway, Google Cloud Run, or a server using Docker instructions. It can generate an MCP_AUTH_TOKEN, configure a connector password, verify health and OAuth endpoints, and print connection details.

Tools and capabilities

Available areas include:

• Recovery, sleep, strain, HRV, resting heart rate, respiratory rate, VO2, and weight trends
• Sleep-stage timelines, sleep metrics, sleep need, calendar views, and performance comparisons
• Strength Trainer workouts, sets, personal records, and exercise lookup
• Journal behavior records and behavior-impact analysis
• Stress timelines, live heart rate, activity state, and live stress
• Smart Alarm and configurable heart-rate zones
• Whoop Coach, community leaderboards, hidden metrics, and women's health data
• Fifteen documented write tools across workouts, journals, profile data, alarms, zones, and sleep records

Limitations and notes

The totem MCP server uses Whoop’s private iOS API rather than the public developer API. The repository notes that this approach is not permitted by Whoop’s terms, so operators should review that risk before installing it. Authentication requires a Whoop account and may require an SMS code when multifactor authentication is enabled.

Whoop is the only completed adapter described in the repository. Fitbit, Apple Watch, and Garmin support are identified as work in progress, not current integrations. Remote operation also requires a deployment host and authentication configuration, while local mode is limited to the machine running the process.