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

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.