WHOOP Health Signals MCP server

mcp-server-whoop

A local-first, read-only Model Context Protocol server for WHOOP. It gives MCP-compatible AI clients compact recovery, sleep, strain, HRV, heart-rate, workout, and body-measurement signals without sending your WHOOP credentials through a hosted third party.

Why this server

• Standard MCP over stdio, usable by any client that supports local MCP servers
• Local WHOOP OAuth flow with each user's own WHOOP developer application
• Access and rotating refresh tokens remain on the user's machine
• Five focused read-only tools instead of a noisy API dump
• Per-record local timestamps, so travel does not shift sleep or workout dates
• Explicit processing status, with no older recovery substituted while a new sleep is pending
• Score-derived metrics appear only for SCORED records; live current-cycle strain is labeled provisional_strain
• Human-scale hours, minutes, calories, and heart-rate-zone minutes
• No raw identifiers, OAuth secrets, or raw continuous heart-rate claims in tool output
• No hosted relay, telemetry, database, generic HTTP tool, raw SQL, or install lifecycle scripts
• Reproducible tarball security audit, CycloneDX SBOM, CodeQL, Gitleaks, dependency review, and OpenSSF Scorecard

This is an independent community project. It is not affiliated with or endorsed by WHOOP. WHOOP data is useful coaching context, not medical advice.

Requirements

• Node.js 18 or newer
• A WHOOP account
• A free application in the WHOOP Developer Dashboard
• An MCP-compatible AI client

Quick start

1. Create a WHOOP developer application and register http://127.0.0.1:8765/callback.
2. Enable the five read scopes and offline listed below.
3. Run npx -y mcp-server-whoop@0.2.2 auth in a terminal and approve WHOOP access.
4. Run npx -y mcp-server-whoop@0.2.2 status to confirm the local grant exists.
5. Add the stdio command npx -y mcp-server-whoop@0.2.2 to your AI client's MCP configuration.
6. Restart or reload the client, then ask: Use WHOOP to summarize my recovery and sleep from the last 7 days.

The authorization command and the AI client must run as the same operating-system user, or both must set WHOOPCREDENTIALSFILE to the same private file. The package never asks you to paste WHOOP tokens into an AI conversation.

The documentation pins an exact reviewed version by default. Use @latest only if you explicitly want your client to follow future releases without reviewing them first.

1. Create your WHOOP application

Create an application in the WHOOP Developer Dashboard and register this exact redirect URL:

http://127.0.0.1:8765/callback

Enable these scopes:

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

offline is required because WHOOP access tokens expire and WHOOP rotates refresh tokens.

2. Authorize locally

Run:

npx -y mcp-server-whoop@0.2.2 auth

The command prompts for your WHOOP client ID and masks the client secret, opens WHOOP consent in your browser, validates the OAuth state, and saves the resulting grant locally.

Credentials are stored at:

Shortened. The full README is on GitHub.