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