Whoop

You can run a dedicated MCP server that connects to the WHOOP API to retrieve sleep, recovery, and physiological cycle data for use with LLMs. This server handles OAuth authentication, token refresh, and exposes data through MCP endpoints so your AI applications can access WHOOP data securely and efficiently.

How to use

Set up and run the WHOOP MCP Server, then use it from your MCP client to fetch sleep, cycle, and recovery data. You will authenticate once, then your client can request: recent cycles with strain and HR data, detailed sleep data by ID, sleep for a specific cycle, and recovery metrics for a cycle.

How to install

Prerequisites you need before installing are Node.js 20 or higher, a WHOOP account, and API credentials (Client ID and Client Secret). After preparing these, follow the steps to install and run the server in either STDIO (local process) or HTTP (network) mode.

# Install dependencies and build the project
pnpm install
pnpm build

# OR using npm
npm install
npm run build

# Start in development mode (optional)
pnpm dev

# Manually refresh tokens (optional)
pnpm refresh-token

Configuration and running in STDIO mode (Claude Desktop)

If you plan to use Claude Desktop in STDIO mode, provide your WHOOP credentials through environment variables and point the client to the local stdio interface. This mode offers better performance and reliability.

# Example Claude Desktop config for STDIO mode
{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/Users/yourname/projects/whoop-mcp/dist/stdio.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Configuration and running in HTTP mode

If you prefer HTTP mode, start the HTTP server and use its URL in your MCP client configuration.

# Start the HTTP server (example)
pnpm start
# or
node dist/http.js

# Server URL
http://localhost:3002/mcp

# Claude Desktop HTTP config example
{
  "mcpServers": {
    "whoop": {
      "url": "http://localhost:3002/mcp"
    }
  }
}

Security and credentials

Keep your API credentials secure. Do not commit environment files or token files. The server stores access tokens locally and refreshes them automatically.

Troubleshooting

If you see authentication errors, run the authentication flow to obtain fresh tokens. If you encounter resource errors, ensure your WHOOP app has the required scopes and that tokens are valid.

Data interpretation notes

Recovery scores use a color scheme to indicate readiness: Green (67–100%) means you're ready for high strain, Yellow (34–66%) indicates moderate readiness, and Red (0–33%) suggests focusing on recovery. The Strain scale ranges from 0 to 21, with higher values showing greater cardiovascular load.

Available tools

get-recent-cycles

Retrieves recent physiological cycles with strain and heart rate data Using parameters limit and days to control the number of cycles returned.

get-sleep-by-id

Gets detailed sleep data for a specific sleep activity by its UUID sleepId.

get-sleep-for-cycle

Retrieves sleep data associated with a particular physiological cycle identified by cycleId.

get-recovery-for-cycle

Fetches recovery metrics for a specific cycle, including HRV and readiness scores.