whoop-mcp

WHOOP MCP Server

A Model Context Protocol (MCP) server for the WHOOP API. Gives any MCP-compatible client (Claude Code, Claude Desktop, etc.) read access to your WHOOP biometric data -- recovery, sleep, strain, workouts, and more.

Features

• Full coverage of the WHOOP Developer API v2
• OAuth 2.0 authentication with token refresh
• Sleep analysis (stages, efficiency, respiratory rate)
• Recovery scores (HRV, resting heart rate, SpO2, skin temp)
• Strain and cycle data
• Workout tracking with heart rate zones
• Pagination support for all collection endpoints
• TypeScript with full type definitions

Prerequisites

• Node.js 18+
• WHOOP account with an active membership
• WHOOP Developer App -- register at developer.whoop.com

Quick Start

1. Clone and install

git clone https://github.com/AaronRoeF/whoop-mcp-server.git
cd whoop-mcp-server
npm install

2. Register a WHOOP Developer App

1. Go to developer.whoop.com
2. Create a new application
3. Set the redirect URI to http://localhost:3000/callback
4. Note your Client ID and Client Secret

3. Configure environment

cp env.example .env

Edit .env with your credentials:

WHOOP_CLIENT_ID=your_client_id
WHOOP_CLIENT_SECRET=your_client_secret
WHOOP_REDIRECT_URI=http://localhost:3000/callback

4. Build

npm run build

5. Authenticate with WHOOP

npm run auth

This starts a local web server, opens your browser, and walks you through the WHOOP OAuth flow. On success, tokens are saved to whoop-tokens.json (gitignored).

6. Add to Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
      "cwd": "/absolute/path/to/whoop-mcp-server"
    }
  }
}

Or for Claude Desktop, add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
      "cwd": "/absolute/path/to/whoop-mcp-server"
    }
  }
}

The start-mcp-server.js script automatically loads saved tokens, refreshes them if expired, and starts the MCP server.

Available Tools

User

| Tool | Description | |------|-------------| | whoop-get-user-profile | Get profile info (name, email) for the authenticated user | | whoop-get-user-body-measurements | Get height, weight, and max heart rate | | whoop-revoke-user-access | Revoke the current access token |

Cycles

| Tool | Description | |------|-------------| | whoop-get-cycle-by-id | Get a specific physiological cycle by ID | | whoop-get-cycle-collection | Get all cycles (paginated, with date filters) | | whoop-get-sleep-for-cycle | Get sleep data associated with a specific cycle |

Recovery

| Tool | Description | |------|-------------| | whoop-get-recovery-collection | Get recovery records (paginated, with date filters) | | whoop-get-recovery-for-cycle | Get recovery data for a specific cycle |

Sleep

| Tool | Description | |------|-------------| | whoop-get-sleep-by-id | Get a specific sleep record by ID | | whoop-get-sleep-collection | Get sleep records (paginated, with date filters) |

Workouts

| Tool | Description | |------|-------------| | whoop-get-workout-by-id | Get a specific workout record by ID | | whoop-get-workout-collection | Get workout records (paginated, with date filters) |

OAuth

| Tool | Description | |------|-------------| | whoop-get-authorization-url | Get the OAuth authorization URL | | whoop-exchange-code-for-token | Exchange an authorization code for an access token | | whoop-refresh-token | Refresh the access token using a refresh token | | whoop-set-access-token | Manually set the access token for API calls |

OAuth Setup Details

WHOOP uses OAuth 2.0. The flow works like this:

1. Register your app at developer.whoop.com and set the redirect URI to http://localhost:3000/callback
2. Run npm run auth -- this starts a local server and opens the WHOOP authorization page
3. Authorize the app -- log in to your WHOOP account and grant access
4. Tokens are saved automatically to whoop-tokens.json

Access tokens expire after ~1 hour. The start-mcp-server.js script handles automatic refresh on startup. If refresh fails, re-run npm run auth.

Required OAuth Scopes

The server requests these scopes:

• read:recovery
• read:cycles
• read:workout
• read:sleep
• read:profile
• read:body_measurement

Pagination

Collection endpoints accept these optional parameters:

| Parameter | Type | Description | |-----------|------|-------------| | limit | number | Max records to return (up to 25) | | start | string | Return records after this time (ISO 8601) | | end | string | Return records before this time (ISO 8601) | | nextToken | string | Pagination token from previous response |

Project Structure

src/
  index.ts          Entry point
  mcp-server.ts     MCP server with tool definitions and handlers
  whoop-api.ts      WHOOP API client (OAuth + all endpoints)
  types.ts          TypeScript type definitions
auth-app.js         Local OAuth web server for initial authentication
start-mcp-server.js MCP server launcher with auto token refresh
env.example         Environment variable template

Development

npm run build       # Compile TypeScript
npm start           # Run the compiled server
npm run dev         # Run with tsx (hot reload)
npm run auth        # Run the OAuth authentication flow
npm run start-mcp   # Start MCP server with saved tokens

License

MIT -- see LICENSE for details.

Acknowledgments

• WHOOP Developer Platform for the API
• Model Context Protocol for the MCP specification