Whoop MCP

WHOOP MCP Server

A 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.x minor 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.

Table of contents

• What this is
• Install (one line via uvx)
• Install with your agent
• Install from source
• Analysis skill: whoop-insights
• Quick start
• Tool catalog
• MCP resources
• Data model
• Sync model
• Event feed
• Exports
• What's not supported
• Updating
• Operations
• Security and privacy
• Development
• For agents building on this repo
• Versioning

What this is

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.

Install (one line via uvx)

# 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=" " \ WHOOP_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).

Install with your agent

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.

Install from source (for development)

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).

Quick start

Once the server is registered, try these prompts:

1. Sync the cache. "Sync my WHOOP data from the last 30 days." Claude calls sync_whoop() and reports per-resource counts.
2. Inspect a day. "Give me yesterday's WHOOP daily summary." Claude calls get_whoop_daily_summary(date="YYYY-MM-DD") and shows a joined cycle + recovery + primary sleep + workouts record.
3. Export. "Export all my cached workouts to ~/whoop-workouts.csv." Claude calls export_whoop(kind="workouts", format="csv", path="...").

Analysis skill: whoop-insights

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.

Tool catalog

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.

MCP resources

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.

Data model

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