WHOOP MCP server

The WHOOP MCP Server provides access to WHOOP fitness and health data through the Model Context Protocol standard, allowing integration with your applications using the complete WHOOP v2 API endpoints with secure OAuth 2.0 authentication.

Prerequisites

Before installing the WHOOP MCP Server, ensure you have:

• Node.js 18 or higher
• A WHOOP Developer Account
• WHOOP API credentials

Installation

Install Dependencies

npm install

Configure WHOOP API Access

1. Visit the WHOOP Developer Platform
2. Create a new application
3. Note your Client ID and Client Secret
4. Set your redirect URI (e.g., http://localhost:3000/callback)

Set Up Environment Configuration

Copy the example environment file and add your credentials:

cp env.example .env

Edit the .env file with your WHOOP API credentials:

# WHOOP API Configuration
WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
WHOOP_REDIRECT_URI=http://localhost:3000/callback

# MCP Server Configuration
MCP_SERVER_PORT=3001

Build and Run the Server

# Build the project
npm run build

# Run the MCP server
npm start

# Or run in development mode
npm run dev

Authentication Process

The server uses OAuth 2.0 authentication with WHOOP. Follow these steps:

1. Use the whoop-get-authorization-url tool to get the OAuth URL
2. Direct users to the authorization URL in their browser
3. When WHOOP redirects back, copy the authorization code from the URL
4. Share this code with Claude in the chat
5. Claude will exchange the code for an access token
6. Claude will set the access token for subsequent API calls

Important Note About Authorization Codes

After completing the WHOOP authorization in your browser, you'll be redirected to a URL containing an authorization code that looks like:

http://localhost:3000/callback?code=ABC123XYZ789&scope=read:recovery%20read:cycles...

Copy the code parameter value (e.g., ABC123XYZ789) and paste it directly in your chat with Claude to proceed.

Available Tools

User Data Tools

• whoop-get-user-profile - Get basic user profile information
• whoop-get-user-body-measurements - Get body measurements (height, weight, max heart rate)
• whoop-revoke-user-access - Revoke user access token

Cycle Tools

• whoop-get-cycle-by-id - Get specific cycle data by ID
• whoop-get-cycle-collection - Get paginated list of cycles
• whoop-get-sleep-for-cycle - Get sleep data for a specific cycle

Recovery Tools

• whoop-get-recovery-collection - Get paginated recovery data
• whoop-get-recovery-for-cycle - Get recovery data for a specific cycle

Sleep Tools

• whoop-get-sleep-by-id - Get specific sleep record by ID
• whoop-get-sleep-collection - Get paginated sleep records

Workout Tools

• whoop-get-workout-by-id - Get specific workout record by ID
• whoop-get-workout-collection - Get paginated workout records

OAuth Tools

• whoop-get-authorization-url - Get OAuth authorization URL
• whoop-exchange-code-for-token - Exchange authorization code for access token
• whoop-refresh-token - Refresh access token
• whoop-set-access-token - Set access token for API calls

Usage Examples

Getting User Profile

// First set your access token
await callTool('whoop-set-access-token', { accessToken: 'your_access_token' });

// Then get user profile
const profile = await callTool('whoop-get-user-profile', {});

Getting Recent Cycles

const cycles = await callTool('whoop-get-cycle-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

Getting Sleep Data

const sleepData = await callTool('whoop-get-sleep-collection', {
  limit: 5,
  end: '2024-01-31T23:59:59Z'
});

Getting Workout Data

const workouts = await callTool('whoop-get-workout-collection', {
  limit: 10,
  start: '2024-01-01T00:00:00Z'
});

Data Types and Pagination

The server provides comprehensive data for:

• User profiles and body measurements
• Cycles with strain scores and heart rate data
• Recovery scores, HRV, and resting heart rate
• Sleep stages and performance metrics
• Workout activity with heart rate zones

Most collection endpoints support pagination with these parameters:

• limit: Number of records to return (max 25)
• start: Start time filter (ISO 8601)
• end: End time filter (ISO 8601)
• nextToken: Token for next page

Error Handling

The MCP server includes comprehensive error handling for:

• Invalid credentials
• Rate limiting
• Network errors
• Invalid parameters
• Missing required fields

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "whoop" '{"command":"npx","args":["-y","whoop-mcp-server-claude"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "whoop": {
            "command": "npx",
            "args": [
                "-y",
                "whoop-mcp-server-claude"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "whoop": {
            "command": "npx",
            "args": [
                "-y",
                "whoop-mcp-server-claude"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect