WHOOP MCP Server

WHOOP MCP Server is a TypeScript Model Context Protocol (MCP) server that gives MCP-compatible assistants access to personal WHOOP recovery, sleep, strain, and workout data.

The server runs locally over stdio. It authenticates with WHOOP through OAuth 2.0, stores reusable tokens on disk, refreshes tokens when needed, and exposes structured tools that assistants can use for workload planning and recovery-aware context.

Features

• Daily WHOOP recovery, sleep, cycle strain, and workout snapshots
• Sleep-stage and sleep-performance summaries
• Recovery score, HRV, resting heart rate, SpO2, and skin temperature summaries
• Short-window versus long-window trend analysis
• Historical baseline profiles
• Change alerts versus yesterday and personal baseline
• Workload guardrails based on recovery signals
• Local OAuth token cache with refresh-token support

Requirements

• Node.js 20 or newer
• npm
• A WHOOP account
• A WHOOP Developer Dashboard app

Create the WHOOP app at:

https://developer-dashboard.whoop.com

The app must have a redirect URI registered. The default used by this project is:

whoop://mcp/callback

Quick Start

Install dependencies:

npm install

Run the setup wizard:

npm run setup

The wizard asks for:

• WHOOP Client ID
• WHOOP Client Secret
• Redirect URI
• Token cache folder
• OAuth scopes

It then opens the WHOOP authorization page in your browser, exchanges the authorization code for tokens, writes the token cache, and offers to create a local .env file.

Build the MCP server:

npm run build

Authentication

WHOOP uses OAuth 2.0 Authorization Code flow for API access. This project does not collect or store your WHOOP username or password.

The setup wizard stores API tokens in:

.whoop-tokens/tokens.json

By default it also offers to write local MCP settings to:

.env

Both .env and .whoop-tokens/ are ignored by git.

The default OAuth scopes are:

read:profile read:body_measurement read:recovery read:cycles read:sleep read:workout offline

The offline scope is required for refresh-token support. Without it, the server may require a new browser login when the access token expires.

Redirect URI Behavior

WHOOP supports redirect URLs such as https://... and custom schemes such as whoop://....

With the default whoop://mcp/callback redirect, the setup wizard asks you to paste the final redirected URL from the browser after approving access. If your WHOOP app is configured with a loopback redirect such as http://127.0.0.1:8787/callback, the wizard can capture the callback automatically with a temporary local HTTP server.

MCP Tools

Tool	Description
whoop_wellbeing_snapshot	Returns recovery, sleep, cycle strain, workouts, and a workload recommendation for a date.
whoop_sleep_summary	Returns sleep-stage, sleep-performance, recovery, HRV, and resting-heart-rate context.
whoop_training_load_trend	Compares short-window and long-window trends for sleep, recovery, HRV, resting heart rate, and day strain.
whoop_baseline_profile	Computes baseline ranges over a historical window.
whoop_change_alerts	Highlights meaningful changes versus yesterday and baseline.
whoop_workload_guard	Evaluates a proposed workload against current recovery signals.

MCP Resource

Resource	Description
whoop://wellbeing/today	Today's WHOOP wellbeing snapshot as JSON.

MCP Prompt

Prompt	Description
whoop_workload_guardrails	Guidance for using WHOOP data during workload planning without treating it as medical advice.

Configuration

The setup wizard can create .env automatically. You can also create it manually:

Copy-Item .env.example .env

Supported environment variables:

Variable	Required	Description
WHOOP_CLIENT_ID	Yes	OAuth Client ID from the WHOOP Developer Dashboard.
WHOOP_CLIENT_SECRET	Yes	OAuth Client Secret from the WHOOP Developer Dashboard.
WHOOP_REDIRECT_URI	Yes	Registered OAuth redirect URI. Defaults to whoop://mcp/callback.
WHOOP_TOKEN_DIR	Yes	Directory used to read and write WHOOP OAuth tokens. Defaults to .whoop-tokens.
WHOOP_SCOPES	No	Space- or comma-separated OAuth scopes. Defaults to the scopes listed above.

Use an absolute WHOOP_TOKEN_DIR when configuring an MCP client. MCP clients often start servers from a different working directory, and an absolute path avoids token-cache lookup problems.

Running Locally

Validate the project:

npm run typecheck
npm run build

Start the MCP server:

npm run start

The server communicates over stdio, so it will appear idle in a normal terminal until an MCP client connects.

Codex Configuration

Example Codex MCP configuration:

[mcp_servers.whoop]
command = "node"
args = ["C:\\path\\to\\whoop-mcp-server\\dist\\index.js"]

[mcp_servers.whoop.env]
WHOOP_CLIENT_ID = "your-client-id"
WHOOP_CLIENT_SECRET = "your-client-secret"
WHOOP_REDIRECT_URI = "whoop://mcp/callback"
WHOOP_TOKEN_DIR = "C:\\path\\to\\whoop-mcp-server\\.whoop-tokens"

Restart Codex after updating the configuration.

Claude Desktop Configuration

Example Claude Desktop MCP configuration:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["C:\\path\\to\\whoop-mcp-server\\dist\\index.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret",
        "WHOOP_REDIRECT_URI": "whoop://mcp/callback",
        "WHOOP_TOKEN_DIR": "C:\\path\\to\\whoop-mcp-server\\.whoop-tokens"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

Troubleshooting

If setup fails:

• Confirm the Client ID and Client Secret are copied from the WHOOP Developer Dashboard.
• Confirm the redirect URI entered in the terminal exactly matches a redirect URI registered on the WHOOP app.
• Confirm the app has access to the requested scopes.
• Delete .whoop-tokens/ and run npm run setup again if tokens are stale.

If the MCP client cannot fetch WHOOP data:

• Confirm npm run build completed successfully.
• Confirm dist/index.js exists.
• Use an absolute WHOOP_TOKEN_DIR in the MCP client configuration.
• Include WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET in the MCP client environment so token refresh can work.
• Restart the MCP client after changing configuration.

If token refresh fails:

• Confirm WHOOP_SCOPES includes offline.
• Run npm run setup again to create a fresh token cache.
• Avoid running multiple server instances against the same token cache at the same time. WHOOP refresh tokens can rotate, and concurrent refreshes may invalidate one instance's cached token.

Security

• Do not commit .env or .whoop-tokens/.
• Treat WHOOP data as private health-related information.
• Keep the WHOOP Client Secret local to trusted machines.
• Revoke the WHOOP app or delete the token cache if a machine is lost or no longer trusted.

Development

npm run dev
npm run setup
npm run typecheck
npm run build