whoopmcp
whoopmcp is a read-only MCP server for WHOOP data, providing authentication, profile/body measurements, record retrieval, and statistical analysis.
Authentication:
whoop_auth_status,whoop_login,whoop_complete_login,whoop_logoutProfile & Body:
get_profile(user ID, email, name),get_body_measurement(height, weight, max HR)Records:
list_recoveries(recovery score, HRV, RHR),list_sleeps(performance, stages),list_cycles(strain, HR, kJ),list_workouts(sport, strain, zones); get by ID:get_sleep,get_workoutAnalysis:
summarize_period(statistics over a range),metric_trend(trend/slope),correlate_metrics(Pearson/Spearman with lags),compare_periods(compare two periods)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@whoopmcp How did my recovery trend over the last month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
whoopmcp
A read-only MCP server for the WHOOP API v2. It lets an MCP client — Claude Desktop, Claude Code, Cursor, or anything else that speaks the protocol — read and analyse your own WHOOP data: recovery, sleep, strain, cycles and workouts.
Runs locally by default, and your WHOOP credentials never leave your machine
in that mode. Run with WHOOPMCP_TRANSPORT=streamable-http (#27) instead and
that stops being true: the operator of that server now holds other members'
tokens and health data server-side, which makes them a data controller, not
a bystander. See PRIVACY.md's local-mode/hosted-mode split
before hosting this for anyone but yourself.

Install and usage patterns live in the wiki; docs/SETUP.md is the from-scratch walkthrough.
Status. Local mode works today against the real WHOOP v2 API, read-only. The hosted surface (streamable HTTP, OAuth resource server, per-tenant isolation, encrypted token storage, webhooks, metrics) is implemented and has been through the roadmap's security audits (#69, #37); the findings they raised are fixed and closed. Running it hosted for others still needs WHOOP's app approval, not yet granted, which caps a shared deployment at 10 members in the meantime (#33). See Roadmap.
Not affiliated with WHOOP, Inc. "WHOOP" is their trademark. This is an independent client of their public developer API.
What it does
Area | Tools |
Auth |
|
Profile |
|
Records |
|
Local store |
|
Analysis |
|
Alongside the 21 tools it registers 3 prompts (morning_readiness_briefing,
weekly_training_review, sleep_debt_investigation) and one resource
template, whoop://user/{item}, serving profile, latest-recovery,
latest-sleep and latest-cycle.
Every tool that only reads is annotated readOnlyHint; the one exception is
whoop_sync, annotated as a non-destructive, idempotent write because it
upserts fetched records into the local store — it never writes to your
WHOOP account. No MCP tool can mutate your
WHOOP account — the one mutating endpoint WHOOP exposes
(DELETE /v2/user/access) is never registered as an MCP tool, so no model
can revoke your grant. It is reachable only from a terminal on the machine
running the server, as the operator-run whoopmcp delete-member --whoop-user-id N (see Privacy); whoop_logout itself only
deletes the token stored on your own disk.
Questions it is meant to answer:
"How did my recovery trend over the last month?"
"Is my HRV correlated with how long I sleep?"
"Compare my strain in July against June."
What it is not
It reports numbers and the sample size behind them. It is not a medical device, it does not diagnose, and a correlation across a few weeks of your own data is not a causal finding. Talk to a clinician about health decisions.
Related MCP server: whoop-mcp
Install
Requires Python 3.13 or 3.14 — the two newest stable releases, which are the two CI tests.
git clone https://github.com/kurok/whoopmcp
cd whoopmcp
uv venv --python 3.14
source .venv/bin/activate
uv pip install -e .Setup
You need your own WHOOP developer app — this server ships no shared credentials, by design. Full walkthrough in docs/SETUP.md. The short version:
Create an app at developer.whoop.com and note the client ID and secret.
Register a redirect URL. WHOOP does not accept
http://, includinghttp://localhost— usehttps://or a custom scheme such aswhoopmcp://callback.Point the server at them via environment variables.
Claude Desktop / Claude Code
{
"mcpServers": {
"whoop": {
"command": "uvx",
"args": ["whoopmcp"],
"env": {
"WHOOP_CLIENT_ID": "your-client-id",
"WHOOP_CLIENT_SECRET": "your-client-secret",
"WHOOP_REDIRECT_URI": "whoopmcp://callback"
}
}
}
}Then ask your client to run whoop_login, open the URL it returns, approve
the consent screen, and pass the code and state from the redirect back
via whoop_complete_login.
Configuration
Variable | Required | Default | Meaning |
| yes | — | OAuth client ID from the WHOOP dashboard |
| yes | — | OAuth client secret |
| yes | — | Must match a registered redirect URL exactly |
| no | all read scopes + | Space-separated scope list |
| no |
|
|
| no |
| Token and cache location |
| no |
|
|
| no |
| Cache responses on disk |
| no | — | ISO 8601 lower bound for |
| no |
| Per-request timeout, seconds |
| no | — | Bearer token required on |
| no | — | HMAC key for |
The offline scope is requested by default. Without it WHOOP issues no
refresh token and you would re-authorise through a browser every hour.
For a token in your OS keychain rather than a file on disk:
pip install 'whoopmcp[keyring]'
export WHOOPMCP_TOKEN_BACKEND=keyringRecommended on Windows, where the default file backend cannot protect the
token: Windows uses ACLs rather than POSIX modes, so the 0600 the file
backend requests is ignored and the token lands world-readable. The server
warns when it first writes one.
Privacy
Read PRIVACY.md before connecting real data — it is split into local-mode and hosted-mode sections, since they are not the same document. The essential points:
This server sends nothing to its maintainers. No telemetry, no analytics, no phone-home. Traffic goes to
api.prod.whoop.comand nowhere else.Your MCP client does send your data onward. Anything a tool returns is passed to whatever model your client is configured to use — Anthropic, OpenAI, a local model — under that provider's terms, not this project's. This is inherent to how MCP works, and it is health data. Know where it is going.
Tokens are stored locally at mode
0600, or in your OS keychain. On Windows file modes are not enforced — use the keychain backend there.Local mode: delete everything with
whoop_logout, then removeWHOOPMCP_STATE_DIR, then revoke the app in the WHOOP app under Settings.Hosted mode: an operator holds other members' health data server-side (#13) and is a data controller for it (GDPR Article 9). Per-member export and erasure are operator-run CLI commands, deliberately not MCP tools —
whoopmcp export-member --whoop-user-id N,whoopmcp delete-member --whoop-user-id N(revokes the member's WHOOP grant upstream and forgets their local token and principal link — nothing more), andwhoopmcp erase-member --whoop-user-id N(also revokes the grant, then additionally erases the member's stored health data, webhook events, and audit rows) — andwhoopmcp enforce-retention --max-age-days Ndeletes data past a configured age when an operator schedules it. This project takes no backups of its own in either mode.
Rate limits
WHOOP's documented defaults are 100 requests/minute and 10,000/day,
with X-RateLimit-* headers and a 429 on breach. Collections page at 25
records maximum. Ask for explicit date ranges; an unbounded walk over years
of history will exhaust the quota and the model's context window alike.
Confirmed with WHOOP: the limit is per application (your client_id),
shared across every member who has authorised it — not a separate budget
per member. Running this locally for one person, that distinction is
invisible. Hosting it for several, it is the whole budget: one member's
two-year backfill is roughly 110 requests, about a minute of the entire
app's per-minute quota (#9).
Development
git clone https://github.com/kurok/whoopmcp
cd whoopmcp
uv venv && uv pip install -e '.[dev,lint]'
pytest # tests
ruff check . && ruff format --check .
mypy # strict on src/Built on the official Python SDK's MCPServer — the class FastMCP became
when the SDK went to 2.0. The layering is deliberate:
config.py environment -> Config, validated once at startup
auth.py OAuth 2.0 flow + token storage (file, encrypted file, keychain)
client.py one method per documented WHOOP endpoint, nothing more
store.py persistent store: schema, tenancy enforcement, erasure
analysis.py pure functions over already-fetched records
server.py MCP tool definitionsOnly server.py, webhooks.py and mcpauth.py import mcp — enforced by
tests/test_module_map.py; CONTRIBUTING.md carries the full 18-module map.
analysis.py holds no network code and client.py holds no statistics, so
each can be tested without the other.
Roadmap
Issue | Work |
#33 | [human] Submit the WHOOP app for approval; lifts the 10-member cap on hosted deployments |
Everything else the roadmap tracked — including both security audits (#69,
#37), the whoopmcp login terminal flow (#76) and the PyPI/MCP-registry
release plumbing (#34) — is implemented and closed. The package is not yet
on PyPI: publication waits on the name-clash resolution recorded in #34, so
install from a clone (see Install above) until then.
Contributing
See CONTRIBUTING.md. Bug reports and PRs welcome; by participating you agree to the Code of Conduct. To report a security issue, follow SECURITY.md rather than opening a public issue.
Prior art
Several other WHOOP MCP servers exist — among them AshwanthramKL/whoop-mcp, shashankswe2020-ux/whoop-mcp and JedPattersonn/whoop-mcp. If one of them already does what you need, use it.
License
MIT.
Available Tools
16 toolscompare_periodsCompare two periodsARead-only
Compare every summary metric between a baseline period and a later one.
Useful for "did the training block change anything" questions. Returns both periods' summaries and the delta, with sample sizes.
Args: baseline_start: ISO 8601 start of the baseline period. baseline_end: ISO 8601 end of the baseline period. comparison_start: ISO 8601 start of the comparison period. comparison_end: ISO 8601 end of the comparison period.
Inputs: baseline_end (required), baseline_start (required), comparison_end (required), comparison_start (required). Returns: object
correlate_metricsCorrelate two metricsARead-only
Correlate two metrics over a range, sweeping a range of day-offsets.
Joins the two metrics by UTC calendar date rather than by cycle, and reports Pearson's r and Spearman's rho at every lag from -lag_days to +lag_days (inclusive), each with its own sample size. A positive lag means metric_a's date precedes metric_b's by that many days -- metric_a "leads". A lag whose surviving pairs fall below 8 is reported as refused rather than omitted.
Correlation here is descriptive, not causal: WHOOP daily samples are autocorrelated (today's recovery is not independent of yesterday's), so do not read a strong r at some lag as proof that one metric drives the other, and do not treat a handful of weeks as a stable finding.
Args: metric_a: First metric name, as in metric_trend. metric_b: Second metric name. start: ISO 8601 start of the range. end: ISO 8601 end of the range. lag_days: Sweep radius in days (default 3, capped at 14); the sweep covers every integer lag from -lag_days to +lag_days.
Raises: ValueError: if lag_days is negative.
Inputs: end (required), start (required), metric_a (required), metric_b (required), +1 more. Returns: object
get_body_measurementGet body measurementsARead-only
Return height in metres, weight in kilograms and max heart rate in bpm.
Inputs: no named parameters. Returns: object
get_profileGet WHOOP profileARead-only
Return the user's WHOOP profile: user id, email, first and last name.
Inputs: no named parameters. Returns: object
get_sleepGet one sleepARead-only
Return a single sleep by its v2 UUID.
Inputs: sleep_id (required). Returns: object
get_workoutGet one workoutARead-only
Return a single workout by its v2 UUID.
Inputs: workout_id (required). Returns: object
list_cyclesList cyclesARead-only
List physiological cycles: day strain (0-21), average and max heart rate, kilojoules.
A cycle is WHOOP's notion of a day, bounded by sleep rather than by midnight, and is the key other records join on.
Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page.
Inputs: end, limit, start, next_token. Returns: object
list_recoveriesList recoveriesARead-only
List recovery records: recovery score (%), HRV (ms) and resting heart rate (bpm).
Args: start: ISO 8601 start of the range, e.g. "2026-07-01T00:00:00Z". Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page.
Inputs: end, limit, start, next_token. Returns: object
list_sleepsList sleepsARead-only
List sleep records: performance (%), efficiency, and stage durations in milliseconds.
Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page. detail: "summary" (default) omits the per-stage sleep-duration breakdown to keep the response small; "full" includes it under "stage_durations", with the units declared once in a top-level "units" key.
Inputs: end, limit, start, detail, +1 more. Returns: object
list_workoutsList workoutsARead-only
List workouts: sport, strain, average and max heart rate, and heart-rate zone durations.
Args: start: ISO 8601 start of the range. Defaults, with end, to the last 7 days when both are omitted. end: ISO 8601 end of the range. limit: Records to return, capped at 25 per page by WHOOP. next_token: Cursor from a previous truncated response, to continue that page. detail: "summary" (default) omits the per-zone heart-rate duration breakdown to keep the response small; "full" includes it under "zone_durations", with the units declared once in a top-level "units" key.
Inputs: end, limit, start, detail, +1 more. Returns: object
metric_trendTrend of one metricARead-only
Compute the direction and rate of change of one metric over a range.
Args: metric: One of "recovery_score", "hrv", "resting_heart_rate", "sleep_performance", "sleep_efficiency", "strain". start: ISO 8601 start of the range. end: ISO 8601 end of the range.
Returns the least-squares slope in metric units per day. A slope is a description of the window requested, not a forecast. Also returns an r² fit-quality figure for that slope -- both as the number and as a word ("strong"/"moderate"/"weak"/"negligible") -- and 7/30/90-day rolling means of the metric over calendar days.
Inputs: end (required), start (required), metric (required). Returns: object
summarize_periodSummarise a periodARead-only
Summarise recovery, sleep and strain over a date range.
Returns mean, standard deviation, median, min and max for each
metric, along with the number of scored records behind each figure
and days_missing -- how many calendar days in the range have no
scored record for that metric, a coverage gap rather than a record
count.
Args: start: ISO 8601 start of the range. end: ISO 8601 end of the range.
Inputs: end (required), start (required). Returns: object
whoop_auth_statusCheck WHOOP authenticationARead-only
Report whether a valid WHOOP token is held, its scopes and its expiry.
Call this first when a data tool fails; it distinguishes "never logged in" from "token expired" from "scope not granted".
Inputs: no named parameters. Returns: object
whoop_complete_loginComplete WHOOP loginA
Finish a login using the code and state from the redirect URL.
Args:
code: The code query parameter from the redirect.
state: The state query parameter from the redirect. It is
verified against the pending login before the code is used.
Inputs: code (required), state (required). Returns: result
whoop_loginStart WHOOP loginARead-only
Return a URL the user must open in a browser to authorise this server.
The user completes the WHOOP consent screen, is redirected to the
configured redirect URI, and then passes the code and state
query parameters back via whoop_complete_login.
Inputs: no named parameters. Returns: result
whoop_logoutForget WHOOP credentialsADestructive
Delete the locally stored WHOOP token.
This does not revoke the grant at WHOOP; do that from the WHOOP app under Settings if you want the authorisation itself withdrawn.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource or analytical operation: auth lifecycle (status, login, complete_login, logout), raw data (profile, body measurement, recoveries, sleeps, cycles, workouts, single gets), and analysis (summarize, trend, correlate, compare). Even similar-sounding tools like list_sleeps vs get_sleep are clearly differentiated by singular vs plural and description.
The naming is mostly verb_noun (get_profile, list_sleeps, summarize_period) but inconsistent: auth tools carry a whoop_ prefix (whoop_login, whoop_complete_login) while data tools do not, and metric_trend breaks the verb_noun pattern by being noun_noun. The style is readable but not uniform.
16 tools is slightly above the typical 3-15 range, but each tool earns its place by addressing a distinct need (auth, each data type, individual records, and analysis). The count is a bit heavy but not bloated, and the domain of WHOOP data access justifies the breadth.
The surface covers the core WHOOP data types (profile, body measurement, recoveries, sleeps, cycles, workouts) plus individual getters for sleep and workout, and adds useful analytical tools. Minor gaps persist: there is no get_recovery or get_cycle by ID, and no way to retrieve a single cycle or recovery directly, but these can be worked around via the list functions.
Maintenance
Related MCP Connectors
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Unofficial Wger MCP — wraps wger Workout Manager REST API (free, no auth for read)
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA local MCP server providing read-only access to WHOOP fitness data via direct OAuth, with a local SQLite cache for offline queries.97 PyPIMIT
- AlicenseAqualityDmaintenanceMCP server providing read access to WHOOP biometric data including recovery, sleep, strain, and workouts.161MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that wraps the Whoop API v2 to let Claude Code pull workouts, sleep, and recovery data.-
- FlicenseBqualityDmaintenanceLocal MCP server for the WHOOP API v2 that provides tools to access recovery, sleep, strain, and workout data, with local history and JSON export.9-