whoop-ai-mcp

An MCP (Model Context Protocol) server that connects AI assistants like Claude to your WHOOP health and fitness data. Ask questions about your recovery, sleep, workouts, and more — all through natural conversation.

📦 Published on the MCP Registry as io.github.shashankswe2020-ux/whoop — discoverable by any MCP-compatible client.

Features

0.7.0 — Trustworthy Personal Analytics: Personal baselines, sleep debt, structured results, aggregate privacy and local diagnostics. See the changelog and release checklist.

• 🏋️ 16 health data tools — recovery, sleep, workouts, cycles, body measurements, profile, summaries, trends, comparisons, record lookups, today's snapshot, calendar, personal baselines, and sleep debt
• 📊 4 MCP Resources — ambient health context (latest recovery, sleep, cycle, profile) available without explicit tool calls
• 💬 5 MCP Prompts — guided conversation starters for common health queries
• 📅 Rich natural date expressions — use "last 7 days", "this week", "last 2 weeks", "last 3 months", "this quarter", "last year", "2026-05", and more
• 📈 Built-in analytics — weekly summaries, trend detection (linear regression), and period comparisons computed server-side
• Personal analytics (0.7.0) — personal baseline distributions and sleep deficits with sample counts, missing-data safeguards and bounded output
• Structured results (0.7.0) — output schemas and matching JSON-text results for all tools
• Aggregate privacy (0.7.0) — five allowlisted tools, no raw resources/prompts, and no caller override of the process policy
• Local diagnostics (0.7.0) — doctor checks configuration and token-file metadata without network or OAuth activity
• 🔐 Secure OAuth2 — browser-based authentication with automatic token refresh
• 🔄 Resilient — automatic retry on rate limits, token refresh on expiry, auto-pagination, clear error messages
• 💾 Secure token storage — tokens stored at ~/.whoop-mcp/tokens.json with 0600 permissions
• ⚡ Zero config — just add your WHOOP app credentials and go
• 📦 Lightweight — only two runtime dependencies (@modelcontextprotocol/sdk + zod)

SOTA scan (WHOOP MCP packages on npm)

Registry snapshot collected 2026-08-30. Versions and publish dates can change; this is an ecosystem comparison, not a source-code security audit.

Package	Latest	Published (UTC)	MCP Registry identity	Runtime deps	Notable signals
whoop-ai-mcp (this repo)	0.6.1	2026-08-07	✅ io.github.shashankswe2020-ux/whoop	2	14 tools, 4 resources, 5 prompts, analytics, HTTP + stdio, OAuth 2.1 connector
whoop-mcp-unofficial	0.6.5	2026-08-29	✅ io.github.davidmosiah/whoop-mcp	6	20+ tools, SQLite cache, privacy modes
mcp-server-whoop	0.2.2	2026-07-17	✅ io.github.Yadheedhya06/mcp-server-whoop	2	Read-only/local-first, npm provenance, SBOM and security checks
@souravpn/whoop-mcp	1.0.2	2026-05-27	✅ io.github.souravpn/whoop-mcp	1	Simple standalone server with OAuth setup
@nchemb/whoop-mcp	0.2.0	2026-04-27	—	4	Shared OAuth relay and local SQLite cache
whoop-mcp-server	0.0.5	2026-03-13	—	2	WHOOP Developer Platform API server
whoop-mcp	0.1.2	2026-03-11	—	1	Server built with the xmcp framework
@roebot0/whoop-mcp	1.0.0	2026-04-06	—	3	Axios-based server and separate auth command
@alacore/whoop-mcp-server	1.0.1	2025-10-09	—	2	API v2 integration; requires pnpm

Findings

• MCP Registry discoverability is now table stakes: at least three alternatives also publish mcpName identities.
• The leading portability trade-off remains local-first/no-infrastructure operation versus richer remote hosting, caching, or relay features.
• Current best practice is to document security controls, test/verification commands, provenance or SBOM metadata, and the exact transport/auth model. This project provides the first two and supports both local stdio and authenticated Streamable HTTP; it does not claim to be a security audit.

Published 0.6.1 strengths

• 14 domain and analytical tools, 4 ambient resources, and 5 prompts in one standalone package.
• No database, relay service, or framework runtime dependency; only the MCP SDK and Zod are required.
• Published to npm and the official MCP Registry, with documented OAuth, token refresh, retries, caching, HTTP hardening, and Inspector verification.

The table above is the historical August 30 snapshot, so its 14-tool count is intentional. Version 0.7.0 adds two tools; its scope and evidence are in the September feature scan.

Evidence and reproducibility: package names, versions, publish dates, dependency counts, descriptions, and mcpName values come from the npm Registry search and package manifests. Feature notes were checked against each package's published metadata/README where available. Re-run the scan with:

curl -s 'https://registry.npmjs.org/-/v1/search?text=whoop%20mcp&size=20'

🎥 Video Walkthrough

Watch a detailed walkthrough of setting up and using whoop-ai-mcp with Claude Desktop:

Covers: creating a WHOOP Developer App, configuring Claude Desktop, OAuth authentication, and querying your health data through natural conversation.

Prerequisites

1. A WHOOP account with an active membership
2. A WHOOP Developer App — create one at developer.whoop.com
   • Set the redirect URI to http://localhost:3000/callback
3. Node.js >= 20

Get a WHOOP

Don't have a WHOOP yet? Here's how to get started:

• 🛒 Buy a WHOOP on Amazon — WHOOP peak on Amazon
• 🔗 Join WHOOP directly — whoop.com/membership

Quickstart (MCP Registry)

This server is published on the official MCP Registry. MCP clients that support the registry can discover and install it automatically:

Server name: io.github.shashankswe2020-ux/whoop

You can also browse it via the registry API:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.shashankswe2020-ux/whoop"

Quickstart (Claude Desktop)

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["whoop-ai-mcp"],
      "env": {
        "WHOOP_CLIENT_ID": "your_client_id",
        "WHOOP_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Replace your_client_id and your_client_secret with the credentials from your WHOOP Developer App.

On first launch, a browser window will open for you to authorize access to your WHOOP data. After authorizing, tokens are cached locally and refresh automatically.

Then ask Claude something like:

"How am I doing today?"

"Show me my sleep data from the last 3 days"

"What workouts did I do this month?"

"Is my HRV trending up or down?"

"Give me a weekly health summary"

"Show me my recovery calendar for last 2 weeks"

whoop-mcp connected in Claude Desktop:

Chatting with WHOOP data through Claude:

Weekly Health Report demo (Claude Desktop):

Installation

Via npx (recommended)

No installation needed — Claude Desktop runs it automatically with the config above.

Global install

npm install -g whoop-ai-mcp

From source

git clone https://github.com/shashankswe2020-ux/whoop-mcp.git
cd whoop-mcp
npm install
npm run build

Setup wizard (whoop-ai-mcp setup)

For a guided installation that writes the Claude Desktop config (or prints the registration command for Claude Code, Codex, or GitHub Copilot) and verifies your WHOOP credentials in one go:

npx whoop-ai-mcp setup

Flags:

• --client=claude-desktop (default) writes/merges claude_desktop_config.json with an automatic .bak backup.
• --client=claude-code prints the equivalent claude mcp add command.
• --client=codex prints the equivalent codex mcp add command (registers the server in ~/.codex/config.toml).
• --client=copilot prints the equivalent code --add-mcp command for GitHub Copilot in VS Code.
• --verify runs the OAuth flow end-to-end and fetches your profile to confirm everything is wired correctly before exiting.
• --client-id / --client-secret skip the interactive prompts (useful for scripts; secrets entered interactively are masked).

If WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET are already exported in your shell, the wizard uses them automatically — no prompts. Combine with --verify to do a one-shot config-correctness check:

WHOOP_CLIENT_ID=... WHOOP_CLIENT_SECRET=... npx whoop-ai-mcp setup --verify

If the Claude Desktop config file already contains a whoop MCP entry from a previous setup, the wizard short-circuits — it reads the existing credentials, prints Existing whoop entry found in <path>, and either verifies them (with --verify) or exits without rewriting the file. To overwrite an existing entry, pass explicit --client-id / --client-secret flags.

Precedence: --client-id / --client-secret flags > existing claude-desktop config > WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET env vars > interactive prompts.

Example session:

shashankmishra@Shashanks-MacBook-Pro ~ % npx whoop-ai-mcp setup --client=claude-desktop
WHOOP MCP — Setup Wizard
------------------------

WHOOP Client ID (from https://developer.whoop.com): xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
WHOOP Client Secret (input hidden): ****************************************************************

Claude Desktop config written: /Users/shashankmishra/Library/Application Support/Claude/claude_desktop_config.json
Previous config backed up to: /Users/shashankmishra/Library/Application Support/Claude/claude_desktop_config.json.bak
Restart Claude Desktop to load the new server.

Re-running against an already-configured Claude Desktop install (existing whoop entry in claude_desktop_config.json) short-circuits to a verification-only flow — no prompts, no rewrite:

shashankmishra@Shashanks-MacBook-Pro ~ % whoop-ai-mcp setup --verify
WHOOP MCP — Setup Wizard
------------------------

Target client (claude-desktop / claude-code) [claude-desktop]:
Existing whoop entry found in /Users/shashankmishra/Library/Application Support/Claude/claude_desktop_config.json.

Verifying credentials with WHOOP...
Cached tokens expired, attempting refresh...
Token refresh successful.
OAuth flow complete. Fetching profile...
Profile OK: {"user_id":35253045,"email":"shashank.swe.2020@gmail.com","first_name":"Shashank","last_name":"Mishra"}

Existing config verified — no changes made.

Configuration

Environment Variables

Variable	Required	Description
WHOOP_CLIENT_ID	Yes	Your WHOOP Developer App client ID
WHOOP_CLIENT_SECRET	Yes	Your WHOOP Developer App client secret

Set these in your Claude Desktop config (see Quickstart) or as shell environment variables:

export WHOOP_CLIENT_ID=your_client_id
export WHOOP_CLIENT_SECRET=your_client_secret

Creating a WHOOP Developer App

1. Go to developer.whoop.com
2. Create a new application
3. Set the Redirect URI to http://localhost:3000/callback
4. Set the Privacy Policy URL (required by WHOOP) — you can use https://github.com/shashankswe2020-ux/whoop-mcp or your own URL
5. Enable the following scopes:
   • read:profile
   • read:recovery
   • read:sleep
   • read:workout
   • read:cycles
   • read:body_measurement
6. Copy the Client ID and Client Secret

Tools

get_profile

Get the authenticated user's basic profile — name and email.

Parameters: None

---

get_body_measurement

Get the user's body measurements — height, weight, and max heart rate.

Parameters: None

---

get_recovery_collection

Get recovery scores for a date range. Returns HRV, resting heart rate, SpO2, and skin temp for each day.

Parameters:

Parameter	Type	Required	Description
start	string	No	ISO 8601 or relative expression ("today", "last 7 days", "this week").
end	string	No	ISO 8601 or relative expression. Defaults to now.
limit	number	No	Max records to return (1–25). Defaults to 10.
nextToken	string	No	Pagination token from a previous response.

---

get_sleep_collection

Get sleep records for a date range. Returns sleep stages, duration, respiratory rate, and performance scores.

Parameters:

Parameter	Type	Required	Description
start	string	No	ISO 8601 or relative expression ("today", "last 7 days", "this week").
end	string	No	ISO 8601 or relative expression. Defaults to now.
limit	number	No	Max records to return (1–25). Defaults to 10.
nextToken	string	No	Pagination token from a previous response.

---

get_workout_collection

Get workout records for a date range. Returns strain, heart rate zones, calories, and sport type.

Parameters:

Parameter	Type	Required	Description
start	string	No	ISO 8601 or relative expression ("today", "last 7 days", "this week").
end	string	No	ISO 8601 or relative expression. Defaults to now.
limit	number	No	Max records to return (1–25). Defaults to 10.
nextToken	string	No	Pagination token from a previous response.

---

get_cycle_collection

Get physiological cycles for a date range. Returns strain, calories, and heart rate data per cycle.

Parameters:

Parameter	Type	Required	Description
start	string	No	ISO 8601 or relative expression ("today", "last 7 days", "this week").
end	string	No	ISO 8601 or relative expression. Defaults to now.
limit	number	No	Max records to return (1–25). Defaults to 10.
nextToken	string	No	Pagination token from a previous response.

---

get_sleep_by_id

Get a single sleep record by ID. Returns sleep stages, duration, respiratory rate, and performance scores.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	The sleep record ID.

---

get_workout_by_id

Get a single workout record by ID. Returns strain, heart rate zones, calories, and sport type.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	The workout record ID.

---

get_cycle_by_id

Get a single physiological cycle by ID. Returns strain, calories, and heart rate data.

Parameters:

Parameter	Type	Required	Description
id	number	Yes	The cycle record ID.

---

get_weekly_summary

Get a summarized health report for a given week — average recovery, HRV, RHR, sleep duration and quality, workout count and strain, plus recovery trend direction.

Parameters:

Parameter	Type	Required	Description
week_start	string	No	ISO 8601 or relative expression ("last week", "this week"). Defaults to most recent Monday.

---

compare_periods

Compare health metrics between two time periods — shows improvement or regression in recovery, sleep, and strain.

Parameters:

Parameter	Type	Required	Description
period_a_start	string	Yes	ISO 8601 start of the first period.
period_a_end	string	Yes	ISO 8601 end of the first period.
period_b_start	string	Yes	ISO 8601 start of the second period.
period_b_end	string	Yes	ISO 8601 end of the second period.

---

get_trend

Analyze a health metric trend over time — detects direction (improving/declining/stable), variability, and anomalies using linear regression.

Parameters:

Parameter	Type	Required	Description
metric	string	Yes	One of: recovery, hrv, rhr, sleep_duration, sleep_performance, strain.
days	number	No	Number of days to analyze (7–90). Default: 30.

---

get_today

Get today's complete health snapshot — recovery score, last night's sleep, current strain, and last workout in one call. Perfect for "how am I doing today?" questions.

Parameters: None

Returns: Recovery score with zone, sleep breakdown (hours, stages, performance), current strain, last workout (sport + strain), and a human-readable summary.

Recovery is returned only when it matches the current local cycle and primary sleep. Pending or invalid primary sleep never falls back to an older recovery. Missing optional sleep percentages are null, not zero. data_quality distinguishes missing, pending, stale, unscored, calibrating, invalid and failed sources; cache status and fetch time remain unknown when the client cannot establish them.

For compatibility, sleep.total_hours remains time in bed. Use time_in_bed_hours or asleep_hours explicitly; summaries now use scored asleep stages. The latest workout includes occurred_at and recording percentage and may be historical.

---

get_baselines

Returns personal distributions for HRV, resting heart rate, respiratory rate, asleep hours and recovery score. baseline_days is an integer from 14 to 180 (default 30). Each band includes mean, median, standard deviation, percentiles, sample size and the latest observation's midrank percentile.

The latest observation and current local day are excluded from each baseline. Calibrating, unscored, invalid and unjoinable observations are excluded. A metric needs 14 historical points after exclusions; otherwise its band is null with an insufficient-data status. Constant distributions are labeled explicitly.

get_sleep_debt

Analyzes scored main sleeps using days (3-90, default 14) and optional start (ISO or a supported relative expression). With start, the window extends forward for days calendar days, clamped to evaluation time. Resolved bounds are returned.

total_debt_hours sums observed nightly deficits. Need excludes WHOOP's accumulated debt component and preserves the signed nap adjustment; achieved sleep is light + slow-wave + REM. standing_debt_hours is the latest WHOOP debt value, separately dated, not the deficit sum. Missing nights are not zero-sleep nights; fewer than three usable nights returns null aggregates. Circular local-clock statistics describe consistency and heuristic social jetlag, not clinical diagnoses or recovery forecasts.

Analytics paginate up to 500 records per source and report upstream truncation. Sleep-debt calculations use all selected records but echo at most 30 nights, with a separate output_capped flag. Both tools include a statistical/medical disclaimer.

get_calendar

Get a day-by-day grid of recovery, sleep, and strain for a date range. Perfect for weekly/monthly overviews.

Parameters:

Parameter	Type	Required	Description
days	number	No	Number of days to show (1–90). Default: 7.
start	string	No	Start date — ISO 8601 or relative expression ("last 14 days", "this month"). Defaults to N days ago.

Returns: Per-day grid with recovery score + zone (green/yellow/red), sleep hours, sleep performance, and strain. Includes period averages.

---

Structured Results And Privacy

All tools advertise outputSchema and return validated structuredContent alongside equivalent JSON text for older clients. Provider bodies and internal error details are not returned in tool or resource errors.

Set WHOOP_MCP_PRIVACY_MODE=aggregate in the server process environment to expose only get_weekly_summary, compare_periods, get_trend, get_baselines, and get_sleep_debt. Per-record arrays, latest observations, standing debt, identity fields and exact activity timestamps are omitted. Period bounds are date-only. Raw resources and all five existing prompts are unavailable in this mode because their workflows require raw tools/resources. Tool arguments cannot override the policy.

The default is standard, retaining all 16 tools, four resources and five prompts. The standard-mode resource and prompt lists later in this README do not apply to aggregate mode. To enable aggregation in a client configuration, add "WHOOP_MCP_PRIVACY_MODE": "aggregate" to the server's existing env object. Restart and reconnect after changing the process policy. Aggregate mode minimizes disclosure; it is not anonymization, does not erase previously shared data, and still sends health aggregates to the assistant provider.

get_today and the two new analytics tools use recorded offsets for local-day attribution. Existing calendar and weekly-summary grouping remains UTC for compatibility. An offset is not a timezone database and cannot reconstruct within-sleep DST changes.

Local Diagnostics

For a local build:

npm ci --ignore-scripts
npm run build
node dist/index.js doctor --json

With 0.7.0 installed, use whoop-ai-mcp doctor or whoop-ai-mcp doctor --json directly. The command is not present in 0.6.1.

Checks runtime, configuration presence, privacy/transport settings and token-file metadata without reading token contents, calling WHOOP, launching OAuth or writing files. Exit codes: 0 = locally ready, 1 = remediation needed, 2 = invalid arguments. T