WHOOP MCP Server

A Model Context Protocol server that gives Claude access to your WHOOP health data via the WHOOP Developer API (API v2).

Tools

Parameters: the data tools (get_recovery, get_sleep, get_workouts, get_cycles) accept optional filters:

• limit — number of records to return (default 1 for recovery/sleep, 5 for workouts/cycles; max 25)

• start_date / end_date — ISO 8601 timestamps, e.g. 2024-01-01T00:00:00.000Z

• include_naps — get_sleep only; include nap records (default false)

get_body_measurements and get_profile take no parameters.

Related MCP server: whoop-mcp

Prerequisites

• Node.js 18 or later

• A WHOOP Developer account and OAuth app

Setup

1. Create a WHOOP Developer App

1. Go to https://developer.whoop.com/ and sign in.

2. Create a new application.

3. Add http://localhost:8080/callback as a Redirect URI (or use a custom port — just keep it consistent with WHOOP_REDIRECT_URI).

4. Enable the following scopes on the app — the server requests all of them, and data tools will return empty or fail if any are missing:

   • offline (required — grants the refresh token so you only authenticate once)

   • read:recovery

   • read:sleep

   • read:workout

   • read:cycles

   • read:body_measurement

   • read:profile

5. Copy your Client ID and Client Secret.

2. Install and build

git clone <this-repo>
cd whoop-mcp
npm install
npm run build

3. Configure environment variables

cp .env.example .env

Edit .env:

WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
WHOOP_REDIRECT_URI=http://localhost:8080/callback

Security note: .env is never committed. Tokens are stored in ~/.whoop-mcp-tokens.json with 600 permissions (owner read/write only).

4. Add to Claude's MCP configuration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your_client_id_here",
        "WHOOP_CLIENT_SECRET": "your_client_secret_here",
        "WHOOP_REDIRECT_URI": "http://localhost:8080/callback"
      }
    }
  }
}

You can either set the env vars here or rely on a .env file in the project root (loaded by dotenv).

Claude Code (.claude/settings.json or via claude mcp add)

claude mcp add whoop node /absolute/path/to/whoop-mcp/dist/index.js \
  -e WHOOP_CLIENT_ID=your_client_id \
  -e WHOOP_CLIENT_SECRET=your_client_secret \
  -e WHOOP_REDIRECT_URI=http://localhost:8080/callback

Or manually in .claude/settings.json:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "...",
        "WHOOP_CLIENT_SECRET": "...",
        "WHOOP_REDIRECT_URI": "http://localhost:8080/callback"
      }
    }
  }
}

5. Authenticate

Once the server is running in Claude, call the authenticate tool:

You: Use the authenticate tool to connect my WHOOP account.

Claude will display an authorization URL. Open it in your browser, approve access, and the tokens will be saved automatically to ~/.whoop-mcp-tokens.json.

Tokens refresh automatically — you only need to authenticate once.

Example prompts

What was my recovery score this morning?
Show me my last 7 days of sleep data.
How has my HRV trended over the past month?
What workouts did I do this week and what was my strain?
What are my body measurements on WHOOP?

Token storage

• Tokens are stored in ~/.whoop-mcp-tokens.json (or the path in WHOOP_TOKEN_FILE).

• The file is created with 0600 permissions so only your user can read it.

• Access tokens are refreshed automatically 60 seconds before expiry using the stored refresh token.

Development

# Compile TypeScript in watch mode
npm run dev

# Run directly (after building)
npm start

Troubleshooting