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. Your WHOOP credentials never leave your machine.

Status: pre-alpha scaffold. The structure, tool surface, configuration and test harness are in place; the network and analysis internals are stubbed and raise NotImplementedError. See Roadmap. Nothing here talks to WHOOP yet.

Not affiliated with WHOOP, Inc. "WHOOP" is their trademark. This is an independent client of their public developer API.

What it does

Every data tool is annotated readOnlyHint. There is no write path to your WHOOP account in this server — the one mutating endpoint WHOOP exposes (DELETE /v2/user/access) is deliberately not wired up, so a model cannot revoke your grant. whoop_logout 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.

uvx whoopmcp          # run without installing
# or
pip install whoopmcp

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:

1. Create an app at developer.whoop.com and note the client ID and secret.

2. Register a redirect URL. WHOOP does not accept http://, including http://localhost — use https:// or a custom scheme such as whoopmcp://callback.

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

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=keyring

Recommended 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. The essential points:

• This server sends nothing to its maintainers. No telemetry, no analytics, no phone-home. Traffic goes to api.prod.whoop.com and 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.

• Delete everything with whoop_logout, then remove WHOOPMCP_STATE_DIR, then revoke the app in the WHOOP app under Settings.

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.

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 or keychain)
client.py     one method per documented WHOOP endpoint, nothing more
analysis.py   pure functions over already-fetched records
server.py     MCP tool definitions; the only file that knows about MCP

analysis.py holds no network code and client.py holds no statistics, so each can be tested without the other.

Roadmap

The scaffold is complete and CI is green; these are the tracked gaps.

Each stub raises NotImplementedError naming its issue, and the test suite pins the contract each one must satisfy.

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.