Whoop MCP Server

A Model Context Protocol (MCP) server for accessing Whoop fitness data. Integrate your WHOOP biometric data into Claude, LLMs, and other MCP-compatible applications.

Features

• Comprehensive Overview - All your daily metrics in one call

• Sleep Analysis - Deep dive into sleep performance and quality

• Recovery Metrics - HRV, RHR, and recovery contributors

• Strain Tracking - Day strain with heart rate zones and activities

• Healthspan - Biological age and pace of aging metrics

Quick Start

1. Clone the repository:

2. Create a

Or set as environment variables:

3. Install dependencies:

4. Start the server:

Or for development with hot reload:

The server will run on http://localhost:3000/mcp by default.

Docker Deployment

1. Create a

2. Build the Docker image:

3. Run the container:

The --env-file .env flag automatically loads all environment variables from your .env file.

4. View logs:

5. Stop the container:

The Docker image is based on the official Bun Alpine image. The container includes health checks to monitor the server's status.

Smithery Deployment

This server is configured to work with Smithery, a platform for deploying MCP servers. When deployed on Smithery:

1. Configuration via Query Parameters: Smithery passes your credentials as query parameters to the /mcp endpoint (defined in smithery.yaml):

   • whoopEmail - Your Whoop account email

   • whoopPassword - Your Whoop account password

   • mcpAuthToken - Optional authentication token

2. Automatic Configuration: The server automatically extracts these from query parameters when running on Smithery, so you don't need to set environment variables manually.

3. Deploy Button: Use the Railway deploy button above for quick deployment, or follow Smithery's documentation for other deployment options.

The smithery.yaml file in the repository root defines the configuration schema that Smithery uses to collect your credentials securely.

Configuration

Credentials Configuration

The server supports two methods for providing credentials:

1. Query Parameters (used by Smithery): Pass credentials as query parameters to the /mcp endpoint

   • whoopEmail - Your Whoop account email

   • whoopPassword - Your Whoop account password

   • mcpAuthToken - Optional authentication token

2. Environment Variables (used for local/Docker deployment):

The server will check query parameters first, then fall back to environment variables if not provided.

Optional Authentication

To protect your MCP server from unauthorized access, you can set the MCP_AUTH_TOKEN environment variable. When set, all requests to the /mcp endpoint must include a matching Bearer token:

Or add it to your .env file:

Clients must then include the token in the Authorization header:

Note: If MCP_AUTH_TOKEN is not set, the server will accept all requests (useful for local development).

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

Without Authentication (Local Development)

With Authentication (Recommended)

Replace /absolute/path/to/whoop-mcp/ with the actual path to this directory.

Available Tools

The server provides five main tools for accessing your Whoop data:

whoop_get_overview

Retrieves comprehensive Whoop overview data for a specific date in a single API call.

Parameters:

• date (optional) - Date in YYYY-MM-DD format. Defaults to today.

Returns:

• Cycle Info: Cycle ID, day, date display, sleep state

• Live Metrics: Recovery score, day strain, sleep hours, calories burned

• Gauges: All score gauges from the home screen

• Activities: Today's activities with scores and times

• Key Statistics: HRV, RHR, VO2 Max, respiratory rate, steps with 30-day trends

• Journal: Journal completion status

Example usage:

whoop_get_sleep

Retrieves detailed sleep analysis and performance metrics.

Parameters:

• date (optional) - Date in YYYY-MM-DD format. Defaults to today.

Returns:

• Sleep performance score

• Hours vs needed

• Sleep consistency

• Sleep efficiency

• High sleep stress percentage

• Personalized insights and recommendations

Example usage:

whoop_get_recovery

Retrieves comprehensive recovery deep dive analysis including contributors and trends.

Parameters:

• date (optional) - Date in YYYY-MM-DD format. Defaults to today.

Returns:

• Recovery score (0-100%)

• Recovery contributors:

  • Heart Rate Variability (HRV)

  • Resting Heart Rate (RHR)

  • Respiratory Rate

  • Sleep Performance

• Trend indicators vs 30-day baseline

• Personalized coach insights

Example usage:

whoop_get_strain

Retrieves comprehensive strain deep dive analysis including contributors, activities, and trends.

Parameters:

• date (optional) - Date in YYYY-MM-DD format. Defaults to today.

Returns:

• Strain score with target and optimal ranges

• Strain contributors:

  • Heart Rate Zones 1-3

  • Heart Rate Zones 4-5

  • Strength Activity Time

  • Steps

• Today's activities with individual strain scores

• Trend indicators vs 30-day baseline

• Personalized coach insights

Example usage:

whoop_get_healthspan

Retrieves comprehensive healthspan analysis including WHOOP Age (biological age) and pace of aging metrics.

Parameters:

• date (optional) - Date in YYYY-MM-DD format. Defaults to today.

Returns:

• WHOOP Age (biological age)

• Age status (Younger, Same, Older vs. chronological age)

• Years difference from chronological age

• Pace of aging (e.g., 0.5x = aging slower than average)

• Comparison with previous period

• Weekly date range for healthspan measurement

Example usage:

How It Works

The server automatically handles authentication:

1. Logs in with your email/password on first request

2. Stores the access token (valid for 24 hours)

3. Automatically re-authenticates before token expires

4. Retries failed requests after re-authentication

Security

Best Practices

• Never commit your .env file or share your WHOOP credentials

• The server stores Whoop authentication tokens in memory only (they expire after 24 hours)

• Use when exposing the server to a network or untrusted clients

• Generate strong, random tokens for MCP_AUTH_TOKEN (e.g., using openssl rand -hex 32)

• When running in production or on a network, always set MCP_AUTH_TOKEN

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT - see LICENSE file for details