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

Related MCP server: Whoop MCP Server

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

MCP Resource

MCP Prompt

Configuration

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

Copy-Item .env.example .env

Supported environment variables:

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