WHOOP MCP

whoop-mcp

An [MCP](https://modelcontextprotocol.io) server that syncs your WHOOP data into Postgres and lets AI agents query it.

WHOOP's public API is rate-limited, cursor-paginated, and returns one record at a time. That is fine for a sync job and terrible for an agent that wants to answer "how does my HRV this week compare to my baseline?". So this server splits the job in two:

• a sync path that pulls cycles, recovery, sleep, workouts, and body measurements from the WHOOP API into a documented Postgres schema, keeping the raw JSON of every record alongside the typed columns;
• a query path of MCP tools that read Postgres only. They are fast, never hit WHOOP's rate limits, and keep working offline once data is synced.

Your data lands in a database you own, in a schema you can read with any SQL client, and nothing leaves your machine except calls to WHOOP itself.

Python 3.12+ · MIT · stdio MCP server + CLI · Postgres storage

Contents

• Tools
• Install
• Quickstart
• Configuration
• Register with an MCP client
• How sync works
• Security model
• Development
• Project layout
• License

Tools

Two write-side tools talk to the WHOOP API; everything else reads Postgres only.

days is capped at 365 and limit at 200. All tools return JSON text.

Install

uv tool install whoop-postgres-mcp      # or: pipx install whoop-postgres-mcp

Or run it without installing:

uvx whoop-postgres-mcp --help

You also need a Postgres database (any recent version; 14+ is fine) and a WHOOP developer app. docs/SETUP.md walks through both.

Quickstart

export WHOOP_CLIENT_ID=...

export WHOOP_CLIENT_SECRET=... export WHOOP_REDIRECT_URI=http://localhost:8765/callback export WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop

whoop-mcp init-db # create the whoop schema (idempotent) whoop-mcp auth-url # print the URL to visit; approve access in a browser whoop-mcp connect # paste the code from the redirect URL whoop-mcp sync --all # first backfill; later runs: whoop-mcp sync --days 7 whoop-mcp # serve MCP over stdio

The same flow is available as MCP tools (whoop_auth_url, whoop_connect, whoop_sync) so an agent can drive the whole setup.

Configuration

All configuration is by environment variable. The server validates every variable at startup and exits with a message naming each missing one.

Register with an MCP client

Claude Code:

claude mcp add whoop -e WHOOP_CLIENT_ID=... -e WHOOP_CLIENT_SECRET=... \

-e WHOOP_REDIRECT_URI=http://localhost:8765/callback \ -e WHOOP_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop \ -- uvx whoop-postgres-mcp

Claude Desktop (claude_desktop_config.json) or any client that takes a stdio command:

{

"mcpServers": { "whoop": { "command": "uvx", "args": ["whoop-postgres-mcp"], "env": { "WHOOP_CLIENT_ID": "...", "WHOOP_CLIENT_SECRET": "...", "WHOOP_REDIRECT_URI": "http://localhost:8765/callback", "WHOOP_DB_URL": "postgresql://whoop:whoop@localhost:5432/whoop" } } } }

How sync works

WHOOP's collection endpoints filter on when a record *occurred*, not when it was last modified, and records change after creation (a sleep is created as PENDING_SCORE and scored later). The sync therefore:

1. always re-fetches the last days days, which catches late re-scores;
2. tracks a per-collection watermark (newest_updated_at in whoop_sync_state). If the last sync is older than days, the window is stretched back to the watermark minus a two-day lookback so a gap never leaves a hole;
3. upserts every record on its natural key (id, or cycle_id for recovery), so overlapping windows are harmless and re-running is safe;
4. records per-collection errors in whoop_sync_state and carries on with the other collections rather than aborting the run.

full=true (or whoop-mcp sync --all) drops the lower bound and walks the account's entire history. Body measurements are a single current record and are refreshed on every sync.

Token refresh is proactive (five minutes before expiry) and serialized through a Postgres advisory lock, so the MCP server and a cron-driven whoop-mcp sync can share one token row without racing.

The full data model is documented in docs/SCHEMA.md.

Security model

• Database access is token access. OAuth tokens are stored in plaintext in whoop.whoop_tokens. Anyone who can read that table can call the WHOOP API as you until the refresh token is revoked. Restrict database grants accordingly and treat WHOOP_DB_URL as a secret.
• Read tools never reach the network. Only whoop_connect and whoop_sync talk to WHOOP. Everything else is a SQL query against your database.
• Nothing is written outside Postgres. No files, no caches, no telemetry.
• Scopes are read-only. The app requests read:* scopes plus offline for refresh tokens. It cannot modify anything in your WHOOP account.
• To revoke access, delete the row from whoop_tokens and remove the app from your WHOOP account settings.

Development

git clone https://github.com/cunicopia-dev/whoop-mcp

cd whoop-mcp uv venv && source .venv/bin/activate uv pip install -e ".[dev]"

ruff check . mypy src pytest # pure-logic tests WHOOP_TEST_DB_URL=postgresql://whoop:whoop@localhost:5432/whoop pytest # + live DB tests

The live tests apply the schema and truncate every table in the target database before each test. Point them at a scratch database.

A throwaway Postgres for local testing:

docker run -d --rm --name whoop-pg -e POSTGRES_USER=whoop -e POSTGRES_PASSWORD=whoop \

-e POSTGRES_DB=whoop -p 5432:5432 postgres:16-alpine

Project layout

src/whoop_mcp/

config.py environment variables, validated at startup auth.py OAuth2 flow, token persistence, locked refresh client.py httpx client: pagination, backoff, Retry-After schema.sql the Postgres DDL (applied by whoop-mcp init-db) db.py connection + schema helpers sync.py incremental sync with per-collection watermarks queries.py read-side SQL behind the MCP tools server.py MCP server over stdio + CLI entry point docs/ SETUP.md WHOOP app registration, OAuth walkthrough, DB init, first sync SCHEMA.md column-by-column data model tests/ config, schema, client, auth, sync, and stdio protocol tests

License

MIT. See LICENSE.