Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
uvx whoop-mcp==0.8.5Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
WHOOP_CLIENT_ID=<value> WHOOP_CLIENT_SECRET=<secret> WHOOP_REDIRECT_URI=<value> WHOOP_LOG_LEVEL=<value> WHOOP_LOG_FILE=<value> WHOOP_LOG_JSON=<value> claude mcp add io.github.ashwanthramkl-whoop-mcp -- uvx whoop-mcp==0.8.5In einem Terminal ausführen.
{ "mcpServers": { "io.github.ashwanthramkl-whoop-mcp": { "command": "uvx", "args": [ "whoop-mcp==0.8.5" ], "env": { "WHOOP_CLIENT_ID": "<value>", "WHOOP_CLIENT_SECRET": "<secret>", "WHOOP_REDIRECT_URI": "<value>", "WHOOP_LOG_LEVEL": "<value>", "WHOOP_LOG_FILE": "<value>", "WHOOP_LOG_JSON": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenA local Model Context Protocol (MCP) server that gives an LLM read-only
access to your WHOOP fitness data. Authentication is direct OAuth against
your own WHOOP developer app — there is no third-party proxy in the path.
All records are mirrored into a local SQLite cache at
~/.whoop-mcp-server/whoop.db, and no data ever leaves your machine
except for the authenticated calls the server itself makes to the WHOOP
v2 API.
Current version: 0.8.5 — see CHANGELOG.md.
Pre-1.0 status. The API surface (tool names, response shapes, error codes) is stabilizing but not frozen. Breaking changes may land in
0.xminor bumps during dogfooding. Patch bumps (0.8.x) are bugfix-only. 1.0.0 will be cut when the surface has been stable for 2+ weeks of real use. Pin the minor version in CI if you're building on top of this.
Just want to try it? Copy the prompt in docs/AGENT_INSTALL_PROMPT.md, paste it into Claude Code / Claude Desktop / Cursor / Windsurf, and your agent will do the install end-to-end.
Building on this repo? Start with AGENTS.md and docs/ARCHITECTURE.md — they're the load-bearing conventions and one-page system map.
The WHOOP MCP Server is a small Python process that speaks MCP over stdio.
It exposes WHOOP v2 data (profile, body measurement, cycles, recoveries,
sleeps, workouts) to any MCP-capable client — primarily Claude Desktop and
Claude Code. The server is read-only. It authenticates with WHOOP using an
OAuth app you register yourself, so your tokens never travel through a
third-party server. The WHOOP records you fetch are written to a local
SQLite cache (mode 0o600) so subsequent reads are free and offline, and
the cache file never leaves your machine.
# 1. Create a WHOOP developer app (one-time, free, self-serve):
# https://developer-dashboard.whoop.com/apps/create
# Redirect URI: http://localhost:8000/callback
# Scopes: read:profile read:body_measurement read:recovery
# read:cycles read:sleep read:workout offline
# 2. One-shot OAuth — opens browser, catches callback, saves encrypted tokens.
WHOOP_CLIENT_ID="<your client id>" \
WHOOP_CLIENT_SECRET="<your client secret>" \
uvx --from whoop-mcp whoop-mcp-oauth
# 3. Register with Claude Code. The --env flags are required so the
# server can refresh tokens when the 1-hour access token expires.
claude mcp add whoop --scope user \
--env WHOOP_CLIENT_ID="$WHOOP_CLIENT_ID" \
--env WHOOP_CLIENT_SECRET="$WHOOP_CLIENT_SECRET" \
-- uvx --from whoop-mcp whoop-mcp
No clone, no venv, no absolute paths. Don't have uv? Install it once:
curl -LsSf https://astral.sh/uv/install.sh | sh (or brew install uv).
Paste the prompt in docs/AGENT_INSTALL_PROMPT.md into any MCP-aware agent (Claude Code, Claude Desktop, Cursor, Windsurf, Zed, Aider). The agent will run the install for you.
git clone https://github.com/AshwanthramKL/whoop-mcp.git
cd whoop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
.venv/bin/pytest -q # 183 tests, ~6s, all respx-mocked
Then register with -- /abs/path/to/whoop-mcp/.venv/bin/python /abs/path/to/whoop-mcp/src/whoop_mcp_server.py.
For Claude Desktop, add the equivalent entry to
~/Library/Application Support/Claude/claude_desktop_config.json (macOS),
pointing command at the venv Python and args at src/whoop_mcp_server.py.
Run ./scripts/fresh_install_check.sh if you want a clean-env smoke
of the install path end-to-end (minus the browser OAuth flow).
Once the server is registered, try these prompts:
sync_whoop() and reports per-resource counts.get_whoop_daily_summary(date="YYYY-MM-DD") and shows a
joined cycle + recovery + primary sleep + workouts record.~/whoop-workouts.csv."
Claude calls export_whoop(kind="workouts", format="csv", path="...").Bundled with the repo: skills/whoop-insights.
Install (one command):
whoop-mcp-install-skills # writes to ~/.claude/skills/
That fetches the latest skill from this repo's main branch and drops
it where Claude Code (and Cursor / Windsurf / Zed) auto-discovers
user-scope skills. Restart your MCP client session and ask:
"How am I doing? Run the whoop-insights skill." "Generate my weekly WHOOP report." "Am I overtraining? Check the last 30 days."
The skill pulls 30 days from the cache, computes personal baselines (HRV, recovery, sleep, strain), flags anomalies with evidence, runs two correlations (sleep→next-day-recovery, strain→next-day-recovery), and optionally generates a self-contained HTML dashboard with Chart.js visualizations. Every claim cites a specific date and a specific number — the skill is instructed never to fabricate.
For repo-native developers iterating on the skill itself:
whoop-mcp-install-skills --source ./skills installs from your local
working tree instead of GitHub.
17 tools. All list tools accept start / end as ISO-8601 and auto-paginate.
Every read tool takes fresh: bool = False — pass True to bypass the
cache and hit the WHOOP API, write-through to cache, and return the live
response. Errors are returned as a structured {"error": {...}} envelope;
tools never raise.
Error codes: AUTH_FAILED, RATE_LIMITED, NOT_FOUND, UPSTREAM_ERROR,
VALIDATION_ERROR, CACHE_ERROR, CACHE_EMPTY, FILE_EXISTS,
EXPORT_ERROR, SYNC_ERROR.
The cache is also exposed as read-only MCP resources, so the client can browse date slices without invoking a tool.
All resources return application/json. Bad inputs return the same
{"error": {"code","message"}} envelope used by tools.
Responses are flattened: the WHOOP score wrapper is lifted, milliseconds
become seconds (*_seconds, 1 decimal), kilojoules become calories
(calories, rounded int), heart-rate keys are renamed to avg_hr_bpm /
max_hr_bpm, and sleep stages are named deep_sleep_seconds,
rem_sleep_seconds, light_sleep_seconds, awake_seconds,
in_bed_seconds. Raw user_id, v1_id, and per-record created_at are
dropped.
score_state convention. WHOOP scores are not always computed. When
score_state != "SCORED" (e.g. PENDING_SCORE, UNSCORABLE) every
derived score field is null and the top-level score_state is preserved
so callers know why.
One flattened record per resource:
// Cycle
{
"id": 123456,
"start": "2026-04-20T04:00:00.000Z",
"end": "2026-04-21T04:00:00.000Z",
"timezone_offset": "+00:00",
"score_state": "SCORED",
"strain": 12.4,
"avg_hr_bpm": 62,
"max_hr_bpm": 168,
"calories": 2810
}
// Recovery
{
"cycle_id": 123456,
"sleep_id": "bb68db7b-...",
"score_state": "SCORED",
"recovery_score": 74,
"resting_heart_rate_bpm": 48,
"hrv_rmssd_ms": 87.3,
"spo2_pct": 97.4,
"skin_temp_c": 33.1,
"user_calibrating": false
}
// Sleep
{
"id": "bb68db7b-...",
"cycle_id": 123456,
"start": "2026-04-20T03:10:00.000Z",
"end": "2026-04-20T10:42:00.000Z",
"nap": false,
"score_state": "SCORED",
"sleep_performance_pct": 88.0,
"in_bed_seconds": 27120.0,
"light_sleep_seconds": 12540.0,
"rem_sleep_seconds": 5280.0,
"deep_sleep_seconds": 6840.0,
"awake_seconds": 1080.0
}
// Workout
{
"id": "a91f...",
"start": "2026-04-20T17:00:00.000Z",
"end": "2026-04-20T17:48:00.000Z",
"sport_name": "Running",
"score_state": "SCORED",
"strain": 9.3,
"avg_hr_bpm": 142,
"max_hr_bpm": 176,
"calories": 511,
"distance_meter": 8030.0,
"zone_durations_seconds": {
"zone_zero": 0.0, "zone_one": 120.0, "zone_two": 900.0,
"zone_three": 1440.0, "zone_four": 420.0, "zone_five": 0.0
}
}
fresh=True bypasses the cache, hits the WHOOP API, write-throughs
the result into the cache, and returns the live response.MAX(updated_at) per resource as the cursor.
A fresh DB falls back to the last 90 days. sync_whoop(full=True) pulls
from 2010-01-01 for every resource (do this once on a brand-new cache).sync_whoop with no new upstream data is a
no-op. Combined with snapshot hash dedupe (below), this means the event
feed stays quiet.profile and body_measurement are singleton
snapshots. Before writing, the server compares SHA-256 of the canonical
raw payload against the stored blob. Byte-identical payloads do not
advance updated_at, so no spurious events are generated.get_whoop_events(since, until=None, resources=None, limit=500) is a
chronological feed across all cached resources — pure cache read, no API
calls. The window is exclusive on both ends:
updated_at > since AND updated_at < until. The strict since bound
means you can feed a returned cursor back in as the next since without
re-seeing a row.
Each event wraps a flat record:
{"resource": "sleeps",
"id": "bb68db7b-...",
"updated_at": "2026-04-20T14:12:33.123Z",
"record": { "...flat sleep..." }}
Response:
{"status": "success", "count": 17,
"since": "...", "until": "...",
"events": [...],
"next_cursor": null | "<opaque-base64>"}
next_cursor is an opaque base64 encoding of
updated_at|resource|id for the last returned event. Pass it back as
since to continue. The full triple is used as a tie-broken lower bound,
so events sharing an updated_at are never skipped at a pagination
boundary. Plain ISO-8601 strings as since still work (M5 compat).
Also exposed as MCP resources — see the MCP resources table above.
export_whoop(kind, format, path, start=None, end=None, overwrite=False)
writes flat cached records to disk. Pure data layer — never hits the API.
Run sync_whoop() first.
kind: cycles | recoveries | sleeps | workouts | all.
"all" writes one file per resource (cycles.*, recoveries.*, …)
into the given directory.format: csv (RFC 4180, alphabetically sorted header, nested
values JSON-encoded), jsonl (one record per line, sorted keys), or
parquet (pyarrow, snappy).overwrite: default False. If the destination has content,
returns FILE_EXISTS. True replaces silently.An empty window still yields a file (header-only CSV / empty JSONL / empty Parquet) so downstream tooling sees a consistent artifact.
Spelled out so nobody wastes an issue.
MCP servers don't auto-update. When you installed is when you pinned. How to pick up a new release depends on how you installed:
Run health_check() afterwards — its pypi_update_available component
will confirm the version your MCP client is now running and whether a
newer one is published.
Breaking-change policy: while the project is 0.x, minor bumps
(0.8.x → 0.9.0) may include breaking changes — always called out in
the ### Changed section of CHANGELOG.md. Patch
bumps (0.8.3 → 0.8.5) are bugfix-only. Once we cut 1.0.0,
breaking changes require a major bump. Pin to a known-good 0.x.y if
you can't absorb churn.
~/.whoop-mcp-server/logs/whoop-mcp.log (~1 MB per file, 5 backups).
Env overrides: WHOOP_LOG_LEVEL (default INFO), WHOOP_LOG_FILE
(path; empty string disables the file handler), WHOOP_LOG_JSON
(default true).health_check(live=True) returns a dict with five component
checks (auth, api_reachable, cache_readable, cache_writable,
schema_version) plus an overall verdict healthy | degraded | unhealthy. live=False skips the network probe.whoop-mcp-oauth (after pip install) or
.venv/bin/python src/setup_direct_oauth.py (from source).Retry-After on 429s and
retries with exponential backoff. After the retry budget, the call
surfaces as RATE_LIMITED — tools never raise.Everything runs locally. OAuth tokens are encrypted at rest in
~/.whoop-mcp-server/tokens.json with a key at
~/.whoop-mcp-server/.encryption_key. The SQLite cache file is created
with mode 0o600. No third-party services — the only outbound network
calls are directly to api.prod.whoop.com. Logs do not include
tokens, refresh tokens, the client secret, or raw WHOOP response bodies.
See PRIVACY.md for the complete inventory of what the
server reads, writes, sends, and logs; and how to delete everything
(rm -rf ~/.whoop-mcp-server).
# Run the full test suite (183 tests).
.venv/bin/pytest -q
# Re-record fixtures (live calls, requires creds in env).
.venv/bin/python tests/record_fixtures.py
# Fresh-install smoke test (clones current HEAD into a tempdir and
# verifies the install path end-to-end, minus the browser OAuth flow).
bash scripts/fresh_install_check.sh
Adding a new tool. Add the implementation under src/whoop_mcp_server.py
with an @mcp.tool() decorator, a Pydantic model in src/whoop_models.py
if the response has a new shape, a cache table in src/whoop_store.py if
the resource is persisted, and tests in tests/. Keep the error envelope
(_error_payload / _map_error) — tools never raise.
Release flow. Bump src/__version__.py (single source of truth) →
add a new top section to CHANGELOG.md in
Keep-a-Changelog format → verify SERVER_VERSION in
whoop_mcp_server.py picks up the new value (the test_version_import
test prevents drift) → update version in pyproject.toml → tag
vX.Y.Z on main.
Start here:
Human contributors: CONTRIBUTING.md has the short
version. The test suite runs in ~6s (.venv/bin/pytest -q); every HTTP
call is respx-mocked so you can iterate offline.
Current version: 0.8.5 (see src/__version__.py). Semantic
versioning. Full history: CHANGELOG.md.
Forked from RomanEvstigneev/whoop-mcp-server
(v0.1.x). Substantially rewritten starting at v0.2.0 to use direct WHOOP
OAuth (no third-party proxy), the WHOOP v2 API, Pydantic-flattened
responses, a local SQLite cache with incremental sync, cache-first
reads, an event feed, exports (CSV/JSONL/Parquet), a health_check
tool, structured JSON logging, and 190+ tests (190 as of 0.8.5). Licensed MIT — see
LICENSE for both copyright lines.
mcp-name: io.github.AshwanthramKL/whoop-mcp
Read-only WHOOP v2 data for MCP clients, with local SQLite cache and CSV/JSONL/Parquet exports.
{ "mcpServers": { "io.github.ashwanthramkl-whoop-mcp": { "command": "uvx", "args": [ "whoop-mcp==0.8.5" ], "env": { "WHOOP_CLIENT_ID": "<value>", "WHOOP_CLIENT_SECRET": "<secret>", "WHOOP_REDIRECT_URI": "<value>", "WHOOP_LOG_LEVEL": "<value>", "WHOOP_LOG_FILE": "<value>", "WHOOP_LOG_JSON": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, WHOOP_REDIRECT_URI, WHOOP_LOG_LEVEL, WHOOP_LOG_FILE, WHOOP_LOG_JSON.
Whoop läuft lokal über stdio.
Zuletzt geprüft: 2026-11-08. Read-only WHOOP v2 data for MCP clients, with local SQLite cache and CSV/JSONL/Parquet exports.