Skip to content

Usage Patterns

Jump to bottom
kurok edited this page Aug 15, 2026 · 1 revision

Usage Patterns

Four ways this server actually gets used, from lightest to heaviest.

1. Live local analysis (the default)

No persistence beyond the token, every tool call fetches live from WHOOP. Just install, log in, and ask your MCP client things like:

  • "How did my recovery trend over the last month?" → metric_trend
  • "Is my HRV correlated with how long I sleep?" → correlate_metrics
  • "Compare my strain in July against June." → compare_periods
  • "Which days was I an outlier this quarter?" → whoop_outliers
  • "What's my longest recovery streak above 66%?" → whoop_streaks

Three built-in prompts package the common rituals: morning_readiness_briefing, weekly_training_review, sleep_debt_investigation. Resources at whoop://user/profile, whoop://user/latest-recovery, whoop://user/latest-sleep and whoop://user/latest-cycle give a client cheap ambient context.

Mind the shared budget: WHOOP allows 100 requests/minute and 10,000/day per app, across every member using your client id. The built-in rate limiter queues rather than fails, and analysis tools cap themselves at 1000 records per call.

2. The persistent local store

Opt in with WHOOPMCP_CACHE=true, then:

.venv/bin/whoopmcp backfill --whoop-user-id <your-id>   # full history, resumable

After that, the whoop_sync tool (or periodic calls to it from your client) keeps the store current from an updated_at high-water mark — one request per collection in steady state. Every analysis tool then reads locally: faster, no rate-budget spend, and coverage metadata (whoop_data_coverage, per-response range_coverage) tells the model honestly which windows are synced rather than letting an empty range read as "no activity".

Deletions upstream are invisible to a forward sync; the reconcile-webhooks CLI closes that hole over a bounded recent window, and declines mass soft-deletes when a listing looks truncated.

3. Hosted mode (multi-member, streamable HTTP)

.venv/bin/whoopmcp --transport streamable-http --host 0.0.0.0 --port 8000

Adds /health, /ready, and — when configured — /metrics (Prometheus, gated on WHOOPMCP_METRICS_TOKEN; per-member series need WHOOPMCP_METRICS_SALT) and /webhooks/whoop (WHOOPMCP_WEBHOOKS_ENABLED=true, HMAC-verified, replay-bounded, rate-limited before the body is read). Enabling webhooks forces the on-disk store automatically.

Hosting for anyone but yourself makes you a data controller — read PRIVACY.md's hosted-mode section first, and know that WHOOP caps unapproved apps at 10 members (#33).

4. The operator command set

Everything privacy-sensitive is CLI-only, never an MCP tool — a model can ask questions; it cannot export, erase, or revoke.

Command What it does
whoopmcp doctor config / credentials / store / sync, one sentence each
whoopmcp login terminal OAuth flow; stores the token locally
whoopmcp backfill --whoop-user-id N resumable full-history import
whoopmcp reconcile-webhooks --whoop-user-id N [--window-days 30] close dropped-deletion holes, apply corrections
whoopmcp replay-webhook --trace-id ID re-run a stored webhook event
whoopmcp export-member --whoop-user-id N [--out FILE] data-subject export, one JSON document, written 0600
whoopmcp erase-member --whoop-user-id N revoke upstream + delete every stored row, then VACUUM
whoopmcp delete-member --whoop-user-id N revoke upstream + forget token and principal link
whoopmcp enforce-retention [--max-age-days 730] the retention job cron actually runs

Wire enforce-retention and reconcile-webhooks into cron/systemd timers on any long-lived deployment; nothing schedules them in-process, by design.

Clone this wiki locally