@davidbatista/whoop-mcp-server

whoop-mcp-server

Unofficial MCP server for connecting AI agents to the WHOOP API.

Unofficial project: this repository is not affiliated with, endorsed by, sponsored by, or supported by WHOOP, Inc. WHOOP is a trademark of its respective owner. Use this project only with your own WHOOP account and according to WHOOP's Developer Terms and API policies.

What it does

whoop-mcp-server lets MCP-compatible agents read WHOOP data through the official WHOOP OAuth API:

• Profile and body measurements
• Physiological cycles
• Recovery scores, HRV, resting heart rate, SpO2, skin temperature
• Sleep sessions, stages, performance, consistency, efficiency
• Workouts, strain, heart-rate zones and sport metadata
• Daily and weekly workflow summaries for agents
• MCP resources and prompts for agent-native workflows
• Optional SQLite read-through cache
• Privacy modes for summary, structured or raw payloads
• Structured MCP tool outputs and a privacy audit tool
• Human-friendly doctor and auth CLI commands for setup without manual code copying

The server runs over MCP stdio, so it works well as a local integration for agents such as Hermes, OpenClaw, Claude Desktop, Cursor, and other MCP clients.

Security and privacy model

• OAuth tokens are stored locally, not returned to the agent.
• Token file defaults to ~/.whoop-mcp/tokens.json with 0600 permissions.
• Refresh token rotation is protected with a lock file to reduce concurrent-agent refresh races.
• Most tools are read-only after OAuth setup. whoop_revoke_access is intentionally destructive and removes access.
• WHOOP_PRIVACY_MODE defaults to structured; full raw WHOOP payloads are opt-in.
• This project does not provide medical advice. It exposes user-authorized data for analysis by your own tools/agents.

Requirements

• Node.js 20+
• A WHOOP Developer app
• OAuth redirect URI configured in the WHOOP Developer Dashboard

Official WHOOP API docs: https://developer.whoop.com/api/

Install with npx

After npm publication:

npx -y @davidbatista/whoop-mcp-server doctor

For MCP clients, use the package with no subcommand so it starts the MCP stdio server.

Install from source

git clone https://github.com/davidmosiah/whoop-mcp.git
cd whoop-mcp
npm install
npm run build

Environment variables

export WHOOP_CLIENT_ID="your-client-id"
export WHOOP_CLIENT_SECRET="your-client-secret"
export WHOOP_REDIRECT_URI="http://127.0.0.1:3000/callback"

# Optional
export WHOOP_TOKEN_PATH="$HOME/.whoop-mcp/tokens.json"
export WHOOP_SCOPES="read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement"
export WHOOP_PRIVACY_MODE="structured" # summary | structured | raw
export WHOOP_CACHE="sqlite"            # optional: true/sqlite/on
export WHOOP_CACHE_PATH="$HOME/.whoop-mcp/cache.sqlite"

Default scopes:

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

Human setup flow

This is the recommended path for non-technical setup:

npx -y @davidbatista/whoop-mcp-server setup
npx -y @davidbatista/whoop-mcp-server auth
npx -y @davidbatista/whoop-mcp-server doctor

What these commands do:

• setup asks for WHOOP credentials, writes local config, and creates a client config/snippet.
• doctor checks Node.js, required WHOOP env vars, redirect URI, token file, privacy mode and cache.
• auth starts a temporary local callback server, opens the WHOOP authorization page, captures the OAuth code and saves tokens locally.
• doctor --json returns the same setup state in machine-readable form.
• Secrets are stored in ~/.whoop-mcp/config.json with 0600 permissions, so MCP client configs do not need to contain your WHOOP secret.

For automatic auth, configure the WHOOP Developer app redirect URI as:

http://127.0.0.1:3000/callback

MCP client config

Example local config:

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/index.js"]
    }
  }
}

For npm/npx usage after publication:

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "@davidbatista/whoop-mcp-server"]
    }
  }
}

If you do not run setup, you can still provide WHOOP_CLIENT_ID, WHOOP_CLIENT_SECRET and WHOOP_REDIRECT_URI through your MCP client env block. Prefer setup for less secret sprawl.

OAuth flow

Recommended for humans:

npx -y @davidbatista/whoop-mcp-server auth

Manual MCP-client flow:

• Ask your MCP client to call whoop_get_auth_url.
• Open the returned URL and authorize the app.
• Copy the final code or full redirect URL.
• Ask your MCP client to call whoop_exchange_code with that code/URL.
• Then call read tools such as whoop_list_recoveries or whoop_get_profile.

The exchange tool stores tokens locally and intentionally does not return token values.

Tools

Auth/setup

• whoop_get_auth_url - Generate an OAuth authorization URL.
• whoop_exchange_code - Exchange authorization code for local tokens.
• whoop_revoke_access - Revoke WHOOP OAuth access and delete local tokens.
• whoop_connection_status - Check env, token, Node, redirect, privacy and cache readiness without calling WHOOP.

User

• whoop_get_profile - Get basic profile.
• whoop_get_body_measurements - Get height, weight and max heart rate.
• whoop_cache_status - Show optional SQLite cache status.
• whoop_privacy_audit - Show local privacy, cache, env-presence and redaction posture without revealing secrets.

Collections

All collection tools support:

• start: ISO date-time filter
• end: ISO date-time filter
• limit: WHOOP page size, max 25
• next_token: cursor from a previous call
• all_pages: fetch multiple pages
• max_pages: cap for multi-page fetches
• response_format: markdown or json
• privacy_mode: optional override: summary, structured, or raw

Tools:

• whoop_list_cycles
• whoop_list_recoveries
• whoop_list_sleeps
• whoop_list_workouts

Resource reads

• whoop_get_cycle
• whoop_get_sleep
• whoop_get_workout
• whoop_get_cycle_sleep
• whoop_get_cycle_recovery

Workflow summaries

These tools fetch the required WHOOP collections, compute defensive baselines, and return structured coaching context for agents. They are read-only and do not store data locally.

• whoop_daily_summary - Latest recovery/sleep/load signals plus action candidates for the next 24 hours.
• whoop_weekly_summary - Weekly scorecard, prior-window comparison, bottlenecks, action candidates and next-week success metrics.

Resources

• whoop://latest/recovery
• whoop://latest/sleep
• whoop://latest/cycle
• whoop://summary/daily
• whoop://summary/weekly

Prompts

• daily_performance_coach
• weekly_training_review
• sleep_recovery_investigator

Daily summary inputs:

• days: lookback window for baseline, default 10, min 7, max 30
• timezone: display timezone, default UTC
• response_format: markdown or json

Weekly summary inputs:

• days: recent analysis window, default 7
• compare_days: prior comparison window, default 7, use 0 to disable comparison
• timezone: display timezone, default UTC
• response_format: markdown or json

Example prompts for agents

Use the WHOOP MCP server to summarize my last 7 days of sleep and recovery. Compare HRV, RHR, sleep performance, consistency and strain. Do not provide medical advice.

Fetch my latest recovery, latest sleep and workouts from the last 3 days. Give me a practical training recommendation for today based only on the data.

Call whoop_weekly_summary with response_format=json, then turn the bottlenecks and success metrics into a concrete training, sleep and focus plan for next week.

Development

npm install
npm test
npm run typecheck
npm run build

Run locally:

npm run build
node dist/index.js

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Optional local HTTP transport:

WHOOP_MCP_TRANSPORT=http WHOOP_MCP_PORT=3000 node dist/index.js
curl http://127.0.0.1:3000/health

Roadmap

• Public npm package publication
• MCP Registry publication

Disclaimer

This software is provided as-is. It is not a medical device, does not provide medical advice, and should not be used for diagnosis or treatment. Always consult qualified professionals for medical concerns.