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

Related MCP server: whoop-mcp

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

Cycles

Recovery

Sleep

Workouts

OAuth

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:

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