Installation

Installation

The package is not yet on PyPI (the name-clash story lives in #34), so install from a clone. Python 3.13 or 3.14 is required.

1. Install

git clone https://github.com/kurok/whoopmcp
cd whoopmcp
python3.13 -m venv .venv
.venv/bin/pip install -e .            # runtime only
.venv/bin/pip install -e ".[keyring]" # optional: store the token in the OS keychain

The entry point is .venv/bin/whoopmcp. Use that absolute path everywhere below — MCP clients launch the server as a subprocess with no shell profile, so PATH tricks don't apply.

2. Register a WHOOP app

At developer.whoop.com, create an app and note the client id and secret.

• Redirect URI: must be https://… or a custom scheme such as whoopmcp://callback. Plain http://, including http://localhost, is rejected by WHOOP's dashboard — and by this server's own config check, so a mistake fails at startup, not mid-login.
• Scopes: request offline (or no refresh token is issued and the grant dies hourly). The read scopes map 1:1 to tools; read:profile is the one scope carrying directly identifying information and only get_profile needs it.

3. Configure the environment

Required: WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET, WHOOP_REDIRECT_URI.

The common optional knobs (full table in docs/SETUP.md):

Variable	Default	Meaning
WHOOPMCP_SCOPES	all six read scopes + offline	space-separated OAuth scopes
WHOOPMCP_TOKEN_BACKEND	file	file, encrypted-file, or keyring
WHOOPMCP_STATE_DIR	~/.local/state/whoopmcp	token file + cache location
WHOOPMCP_CACHE	false	opt into the persistent local store
WHOOPMCP_TRANSPORT	stdio	stdio or streamable-http

Malformed numeric values fail at startup with the variable named; the outbound rate limits and timeout must be positive, the port 1–65535.

4. Wire up an MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "whoop": {
      "command": "/path/to/whoopmcp/.venv/bin/whoopmcp",
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret",
        "WHOOP_REDIRECT_URI": "whoopmcp://callback",
        "WHOOPMCP_SCOPES": "read:recovery read:sleep read:cycles read:workout read:body_measurement offline"
      }
    }
  }
}

Claude Code

claude mcp add whoop /path/to/whoopmcp/.venv/bin/whoopmcp \
  -e WHOOP_CLIENT_ID=... -e WHOOP_CLIENT_SECRET=... \
  -e WHOOP_REDIRECT_URI=whoopmcp://callback

Your client secret sits in a plaintext client config either way — treat the file like an SSH key.

5. Verify and log in

.venv/bin/whoopmcp doctor

doctor reports configuration, credentials, store and sync state as one honest sentence each. Then either run .venv/bin/whoopmcp login (terminal OAuth flow — preferred) or ask your MCP client to call whoop_login and paste the callback URL into whoop_complete_login.

Troubleshooting

• ConfigError naming a variable — fix that variable; the server refuses to start on a malformed value rather than limping.
• no WHOOP token stored — you haven't logged in yet; run whoopmcp login.
• Windows — POSIX file modes don't protect the token file there; use WHOOPMCP_TOKEN_BACKEND=keyring (the server warns about exactly this).