Totem MCP server
io.github.thebriangao/totem·v1.4.4·121 starsTotem — talk to your wearables with AI. Today: full Whoop access (48 tools).
121 stars28 downloads/wk
Reviews
Write oneNobody has reviewed Totem yet.
If you have run it, two minutes of your experience saves the next person an afternoon.
Totem tools (48, 14 write)
write = sends, deletes, buys or postsRead from the package source without running it. The installed server may list more.
whoop_activity_createwrite actionWRITE: log a generic off-strap activity for a sport_id (call whoop_sports_catalog first to get one) over a start–end window of at least 1 minute. Preview unless confirm:true.
whoop_activity_deletewrite actionWRITE / DESTRUCTIVE: delete a workout/activity. Preview unless confirm:true.
whoop_behavior_impactHow much your tracked behaviors have historically moved recovery/HRV/sleep. Call with NO behavior_id to list every behavior with its impact_uuid + headline effect; then call again with behavior_id set to that impact_uuid (the long UUID, not a numeric id) for the full breakdown.
whoop_calendarMonth-at-a-glance calendar grid for the month containing the given date: each day's recovery STATE — GREEN (high), YELLOW (medium), or RED (low). The grid only exposes the state, not numeric recovery/sleep/strain scores; for a specific day's numbers use whoop_day.
whoop_coach_askwrite actionWRITE (creates a coach conversation): ask Whoop Coach a question and poll up to 30s for the reply. context tells the coach which screen you're asking about — one of HOME, RECOVERY, STRAIN, SLEEP, STRESS, CARDIO_DETAILS, WAKE_UP_REPORT (default HOME). Preview unless confirm:true.
whoop_communitiesLists the communities you belong to (teams, friend groups) with member count and optionally your rank, controlled by team_type (ALL, COMMUNITY, TEAM, BUSINESS), metric (strain, sleep, recovery), and period (day, week, month). Use this to discover community IDs, then whoop_leaderboard to drill into one.
whoop_compareCompare two date windows side by side (e.g. 'this week vs last week') — each metric's average in window A vs window B plus the delta. window: week or month. metrics: any of RECOVERY, SLEEP_PERFORMANCE, DAY_STRAIN, HRV, RHR (defaults to all five).
whoop_cycleCurrent menstrual cycle status for a date: phase (e.g. Luteal Phase), cycle day, typical cycle length, and predicted next-period / ovulation dates. Requires women's-health tracking enabled on the account; fields return null if it isn't set up.
whoop_cycle_logwrite actionWRITE: log a period or ovulation event for a date — pass period:true (optionally period_flow for flow intensity) OR ovulation:true, not both on the same date. Women's-health tracking must be set up on the account first (else the API 400s).
whoop_dayComposite snapshot for any past date: recovery, sleep + stages, day strain, workouts count. Same shape as whoop_today but current_state is always null (not relevant for historical days).
whoop_endpointsSearch the bundled catalog of Whoop iOS API endpoints. Call before whoop_raw to discover paths.
whoop_hidden_metricwrite actionWRITE: show or hide a dashboard metric. metric: BODY_COMP or HEALTHSPAN. action: hide or show.
whoop_hr_zonesCurrent heart-rate zones + max HR + last updated.
whoop_hr_zones_setwrite actionWRITE: set your heart-rate zones. mode=max_hr → pass max_hr (bpm) and Whoop recomputes the 5 zones; mode=custom → pass all 5 zones (ZONE_1..ZONE_5, each with min/max bpm).
whoop_journalYour journal entry for a date: tracked behaviors with values + human-readable names (resolved from the bundled catalog).
whoop_journal_autopopwrite actionWRITE: trigger Whoop to auto-populate the journal from inferred behaviors (HealthKit data, workout patterns).
whoop_journal_catalogSearch the 308-behavior journal catalog to get a behavior_tracker_id and its magnitude type for whoop_journal_log. Filter by substring, magnitude_type (bare, boolean, or magnitude), or category (Drugs & Medication, Health & Symptoms, Hormonal Health, Lifestyle, Mental Wellbeing, Nutrition, Recovery, Sleep & Circadian Health, Supplements).
whoop_journal_logwrite actionWRITE: save the full journal entry for a date — this REPLACES the whole day's entry, so first call whoop_journal to read what's already logged today and resend those entries together with your additions, or they'll be wiped. Use whoop_journal_catalog for each behavior_tracker_id and its magnitude type: bare → pass just the id, boolean → add answered_yes, magnitude → add magnitude_value.
whoop_leaderboardCommunity leaderboard ranking + your own position in it. Auto-discovers your first community if community_id is omitted. metric: recovery, sleep, or strain. window: day, week, or month.
whoop_lift_catalogSearch the 372-exercise Strength Trainer catalog to get the exact exercise_id for whoop_lift_log, lift_exercise, or lift_progression. Filter by name substring, muscle, equipment, movement_pattern, or laterality (BILATERAL, LEFT, RIGHT, ALTERNATING), and read the id from the result.
whoop_lift_custom_exercisewrite actionWRITE: create a custom Strength Trainer exercise based on an existing official one. Requires calling whoop_lift_catalog first.
whoop_lift_exerciseSingle exercise composite: metadata + recent sessions (sets with reps/weight/medal) + PRs. Requires calling whoop_lift_catalog first.
whoop_lift_historyRecent strength workouts with per-exercise aggregates (set count, total reps, tonnage, medals). It does NOT include individual set reps/weights — for those use whoop_lift_exercise, which returns every set for one exercise across your history.
whoop_lift_libraryYour saved Strength Trainer templates. Pass template_id for full detail of one; omit for the list.
whoop_lift_logwrite actionWRITE: log a finished strength workout — pass exercises, each with sets (reps and/or weight in kg and/or time_seconds). Call whoop_lift_catalog first to get valid exercise_ids; preview unless confirm:true.
whoop_lift_progressionMulti-window volume trend for a single exercise: 30-day, 6-month, year segments with avg volume + change % + per-session points. Requires calling whoop_lift_catalog first.
whoop_lift_prsAll Strength Trainer personal records: per-exercise top weight, units, date, medal.
whoop_lift_template_savewrite actionWRITE: create or save-as a Strength Trainer workout template from exercises whose sets can specify reps and/or weight (kg) and/or time_seconds. Call whoop_lift_catalog first for valid exercise_ids; preview unless confirm:true.
whoop_live_hrCurrent heart rate from the strap. Returns is_recording:false + last-known BPM if not actively streaming. Check last_updated_at for staleness.
whoop_live_stateAre you currently in a tracked workout, sleep, or idle? Returns sport name + start time if active.
whoop_live_stressCurrent stress level (terse). Cheaper than whoop_stress if you just want the latest reading.
whoop_performance_assessmentWhoop's performance assessment for a period — recoveries logged vs required, whether an assessment is due, and the next assessment window. period: WEEK or MONTH (default MONTH).
whoop_profileStatic account + body data: name, email, height, weight, max HR, resting HR, hidden metrics, stealth mode.
whoop_profile_updatewrite actionWRITE: change any profile field(s) — pass ONLY what you want to change and the tool fetches your current profile and merges, backfilling everything you didn't touch (Whoop's PUT is non-partial and 422s on a sparse body). Weight is kg and height is meters; preview unless confirm:true.
whoop_rawESCAPE HATCH: call any Whoop endpoint directly — use only when no specific tool fits, and look up the exact path with whoop_endpoints first. Mutating methods (POST/PUT/DELETE) require confirm:true.
whoop_recoveryRecovery deep-dive: score, state, HRV and RHR (each with baseline), respiratory rate, SpO2, skin temp, and sleep performance. (The generic contributors[] array and calibration_state are empty in the current tile shape — the per-metric data is in the typed fields.)
whoop_sleepLast night's sleep deep-dive: all 4 stages (REM/light/SWS/wake) with durations + percentages, the full per-stage hypnogram, efficiency, performance, consistency, disturbances, and in-sleep heart rate. (Sleep HRV, respiratory rate, debt, and latency aren't exposed by this endpoint and return null.)
whoop_sleep_needRecommended bedtime/wake time + sleep need breakdown (baseline + debt + strain need) + smart-alarm eligibility.
whoop_smart_alarmCurrent Smart Alarm state: schedules (per-day-of-week) + global prefs (lower/upper bounds, goal mode, enabled).
whoop_smart_alarm_setwrite actionWRITE: update Smart Alarm. To change WHEN the alarm wakes you, use mode=schedule (needs schedule_id + latest_wake_time) — that's the setting that actually controls the wake time. mode=preferences sets the global goal + enable flags, but its lower/upper_time_bound are ignored by the server whenever an explicit schedule exists, so don't use it to set a wake time. master_enable / master_disable turn
whoop_sports_catalogSearch the 203-sport catalog (numeric sport_id ↔ name) to get the exact sport_id for whoop_activity_create. Filter by a substring of the sport name and read the id straight from the result rather than guessing one.
whoop_strainDay strain deep-dive: score, calories, avg/max HR, time in 6 HR zones, workouts count, steps, strength activity time.
whoop_stressStress monitor for a day: timeline buckets (15-min), current level, baseline, daily min/peak.
whoop_symptom_logwrite actionWRITE: log women's-health symptoms for a date via menstruation (none, spotting, light_flow, medium_flow, heavy_flow), cervical_mucus (5 discharge types — see the param enum; omit to clear), and/or symptoms[] referencing behavior_tracker_ids. Women's-health tracking must be set up, and any symptoms[] require calling whoop_journal_catalog first.
whoop_todayComposite snapshot for today: recovery score, sleep performance + stages, day strain so far, workouts logged today, current activity state.
whoop_trendTrend for one metric across week / month / 6-month windows — per-day points, aggregate stats, and delta vs the prior window. metric is exactly one of: HRV, RHR, RECOVERY, DAY_STRAIN, CALORIES, STEPS, AVERAGE_HR, HOURS_V_NEED, HOURS_V_NEEDED_PERCENT, TIME_IN_BED, SLEEP_PERFORMANCE, SLEEP_EFFICIENCY, SLEEP_CONSISTENCY, SLEEP_DEBT_POST, RESTORATIVE_SLEEP, HR_ZONES_1_3, HR_ZONES_4_5, RESPIRATORY_RATE,
whoop_workoutSingle workout full detail: strain, HR curve, HR zone durations, calories, distance, sport. Strength workouts also include MSK summary. Note: a just-created/logged activity stays 'pending' for a while and errors here until Whoop scores it.
whoop_workoutsRecent workouts — sport, start/end, duration, strain, avg/max HR, and calories. Optional sport-name filter, limit (≤25), and start/end date range; use whoop_workout(activity_id) for one workout's full detail (HR curve, zones).
Public scan report
scanner v0.1.9 · 2026-09-27 · same rubric, same numbers if you re-run it
- Code scan261 source files scanned13/25
- –Live reliabilityno gateway calls yet and no remote to proben/a
- –Tool poisoningtools not inspected (local package is not executed); not countedn/a
- Auth qualitystatic API keys via environment variables6/15
- Maintenancelast push 11 days ago15/15
- Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10
Findings (1)
- highcurl | sh in a script
install.curl-pipedist/cli/setup.js: …s: true })) { await run("sh", ["-c", "curl https://sdk.cloud.google.com | bash"]); } } …
How Totem compares
Against every graded MCP server, from our own scans and uptime checks. Updated after each scan run.
- Safety score
- 65/100
- higher than 20% of 48,255 servers
- Tools
- 48
- the typical server has 7
- Tools that change things
- 29%
- typical: 0%. Fewer write tools means less an agent can break
- GitHub stars
- 121
- more than 95% of 28,688 servers
- Downloads a week
- 28
- more than 15% of 12,191 servers with a package
What its tools let an agent do: 34 read · 14 change
Install Totem in Claude Code, Cursor or VS Code
Runs npx -y @thebriangao/totem on your machine. Read the scan report first; the gateway never runs local packages.
claude mcp add totem -- npx -y @thebriangao/totem
What the publisher says
From the Totem repository's README, as published. We do not edit it. Read it on GitHub
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
- 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 linkShortened. The full README is on GitHub.
Nothing above is checked by us. What we check is on the safety report.
Totem: common questions
- Is Totem MCP server safe?
- With care: it is graded C, so read the findings first (65/100). Read the Totem safety report
- How do I install Totem?
- It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
- Does Totem need an API key?
- Yes. The registry entry asks for
WHOOP_IOS_BEARER_TOKEN,WHOOP_COGNITO_REFRESH_TOKEN. - Is Totem maintained?
- The last commit was 49 days ago (2026-09-16). The latest release is v1.4.4.
- How does Totem compare with other MCP servers?
- safety score 65/100 (higher than 20% of 48,255 servers); tools 48 (the typical server has 7); tools that change things 29% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.