Whoop Mcp Unofficial

by davidmosiah

300 downloads

Not rated

GitHub

About

Unofficial local-first MCP server for WHOOP — recovery, strain, sleep stages, HRV, RHR and workouts. Privacy modes (summary/structured/raw), SQLite cache and doctor CLI for setup. Works with Claude Desktop, Cursor, Windsurf, Hermes, OpenClaw and any MCP-compatible client. Install

Details

Author: davidmosiah
Downloads: 300
Categories: Developer Tools, AI

- OAuth tokens stored locally with 0600 permissions
- Privacy modes: summary, structured, or raw (opt-in)
- Tools for recovery, sleep, cycles, workouts, and profile
- Built-in prompts: daily performance coach, weekly review, sleep investigator
- Resources expose capability and summary endpoints
- Paginated collection tools with filters and privacy override

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Whoop Mcp Unofficial

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

From the repository

Install and configure using npx -y whoop-mcp-unofficial setup (paste WHOOP developer credentials), then npx -y whoop-mcp-unofficial auth (opens browser for OAuth), and npx -y whoop-mcp-unofficial doctor to verify. Add a JSON config snippet to your MCP client. The whoop_connection_status tool checks setup; then ask your agent to call tools like whoop_daily_summary.

`whoop_data_inventory`

Inventory supported WHOOP data domains, auth scope requirements, privacy boundary and recommended first calls. Does not call WHOOP APIs or expose user data.

`whoop_capabilities`

Explain supported WHOOP data, unavailable raw sensor streams, privacy modes, recommended agent workflow, and project links. Does not read WHOOP or expose secrets.

`whoop_agent_manifest`

Machine-readable install, runtime and client guidance for AI agents operating the WHOOP MCP. Does not read WHOOP or expose secrets.

`whoop_quickstart`

Personalized 3-step setup walkthrough for the human user. Adapts to current state (env vars set? token present? what's next?). Call this first when the user asks 'how do I connect WHOOP?'

`whoop_demo`

Returns realistic example payloads of whoop_daily_summary, whoop_wellness_context, and whoop_list_recoveries so agents see the contract before calling real WHOOP APIs. Shapes are verified against the real tools by a build gate, so a parser written against this demo works on live data.

`whoop_profile_get`

Read the shared Delx wellness profile (~/.delx-wellness/profile.json). Returns the user's preferred name, body basics, goals, devices, training context, nutrition context, agent preferences, and missing critical fields. Cross-connector — the same profile is also available from other Delx Wellness MCPs (Oura, Garmin, Nourish, Fitbit, etc). Read-only.

`whoop_profile_update`

Persist a partial patch to the shared Delx wellness profile (~/.delx-wellness/profile.json). REQUIRES explicit_user_intent=true. Top-level fields stored: profile (preferred_name, language, timezone, units, age_or_birth_year, height, weight, sex_or_gender_context), goals, devices, training, nutrition, preferences, safety, notes. NEVER stores OAuth tokens, API keys, refresh tokens, cookies, or any secret-shaped field — writes will be rejected at validation time. Cross-connector — the same profile is read by other Delx Wellness MCPs.

`whoop_onboarding`

Return the 11-question Delx wellness onboarding flow (in English or pt-BR) plus the current shared profile state and missing critical fields. Read-only. The agent should ask these questions one-by-one, then call whoop_profile_update with explicit_user_intent=true to save. The same profile is reused by every Delx Wellness connector (Oura, Garmin, Nourish, etc.) — agents can call the equivalent {connector}_onboarding tools to cover their respective domains, or rely on this one since all connectors share the same questions.

`whoop_get_auth_url`

Generate a WHOOP OAuth authorization URL. This does not read or modify WHOOP data. Use this first when no local token exists.

`whoop_exchange_code`

Exchange a WHOOP OAuth authorization code for local tokens. Tokens are stored locally with 0600 permissions and are never returned by this tool. Gated: requires explicit user intent — agents must not call this autonomously.

`whoop_get_profile`

Get the authenticated user's basic WHOOP profile. Requires read:profile scope.

`whoop_get_body_measurements`

Get the authenticated user's WHOOP body measurements (height, weight, max heart rate). Requires read:body_measurement scope. Not medical advice.

`whoop_list_cycles`

List WHOOP physiological cycles. Supports start/end filters and WHOOP pagination. Requires read:cycles scope.

`whoop_list_recoveries`

List WHOOP recoveries sorted by related sleep start time descending. Returns recovery score, HRV, RHR, SpO2 and skin temperature when scored. Requires read:recovery scope. Not medical advice.

`whoop_list_sleeps`

List WHOOP sleep activities. Returns sleep stages, performance, consistency and efficiency when scored. Supports start/end filters and WHOOP pagination. Requires read:sleep scope. Not medical advice.

`whoop_list_workouts`

List WHOOP workouts. Supports start/end filters and WHOOP pagination. Requires read:workout scope.

`whoop_connection_status`

Check whether local WHOOP env vars, token file, Node version, privacy mode and cache are ready. Does not call WHOOP or expose secrets.

`whoop_cache_status`

Show optional local SQLite cache status. Enable with WHOOP_CACHE=sqlite or WHOOP_CACHE=true.

`whoop_privacy_audit`

Return the local privacy, cache, token-path, env-presence and redaction posture without revealing secret values.

`whoop_revoke_access`

Revoke the current WHOOP OAuth access grant and delete the local token file. Use only when the user explicitly wants to disconnect WHOOP. Gated: requires explicit user intent — agents must not call this autonomously.

`whoop_daily_summary`

Build a privacy-conscious daily performance summary from WHOOP recovery, sleep, cycle and workout data. This workflow tool fetches recent WHOOP v2 records, computes a defensive baseline, and returns readiness, sleep, load, diagnostic signals and concrete action candidates. It does not provide medical advice and does not store data locally.

`whoop_weekly_summary`

Build a weekly WHOOP operating review with recovery, sleep, strain, workouts, bottlenecks, action candidates and next-week success metrics. This workflow tool compares a recent window against a prior window when available. It is intended for coaching and agent workflows, not medical diagnosis.

`whoop_recovery_trend`

Aggregate WHOOP recovery over the last N days (default 30) into a per-metric trend for recovery score, HRV (hrv_rmssd_milli) and resting heart rate. Each metric returns { avg, min, max, slope, direction, n_valid } where slope is a least-squares fit over the chronologically ordered scored records (oldest to newest) and direction is rising, falling, stable or insufficient_data. Use this to answer "is my recovery trending up or down?" without paging the raw collection yourself. Read-only; fetches recent WHOOP v2 records, computes statistics, stores nothing. Not medical advice.

`whoop_sleep_trend`

Aggregate WHOOP sleep over the last N days (default 30) into a per-metric trend for sleep performance percentage, sleep duration (hours) and sleep efficiency percentage. Each metric returns { avg, min, max, slope, direction, n_valid } where slope is a least-squares fit over the chronologically ordered scored sleeps (oldest to newest) and direction is rising, falling, stable or insufficient_data. Use this to answer "is my sleep improving or degrading?" without paging the raw collection yourself. Read-only; fetches recent WHOOP v2 records, computes statistics, stores nothing. Not medical advice.

`whoop_wellness_context`

Normalize WHOOP recovery, sleep, strain and recent workout load into the shared wellness_context shape for exercise recommendation engines and Telegram agents.

`whoop_get_cycle`

Get one WHOOP cycle by numeric cycle id. Requires read:cycles scope.

`whoop_get_sleep`

Get one WHOOP sleep activity by UUID. Requires read:sleep scope. Not medical advice.

`whoop_get_workout`

Get one WHOOP workout by UUID. Requires read:workout scope.

`whoop_get_cycle_sleep`

Get the sleep associated with a WHOOP cycle. Requires read:sleep scope. Not medical advice.

`whoop_get_cycle_recovery`

Get the recovery associated with a WHOOP cycle. Requires read:recovery scope. Not medical advice.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "whoop mcp unofficial": {
            "whoop": {
                "command": "npx",
                "args": [
                    "-y",
                    "whoop-mcp-unofficial"
                ]
            }
        }
    }
}

McpServers

{
    "whoop": {
        "command": "npx",
        "args": [
            "-y",
            "whoop-mcp-unofficial"
        ]
    }
}

whoop-mcp-server

Local-first MCP server that connects AI agents to your WHOOP recovery, sleep, strain and HRV data.

> Unofficial project. Not affiliated with, endorsed by or supported by WHOOP, Inc. WHOOP is a trademark of its respective owner. Use this only with your own WHOOP account and in line with WHOOP's Developer Terms.

Built by David Mosiah for people who use Claude, Cursor, Hermes, OpenClaw or other MCP-compatible agents to think about training, sleep and recovery — without copy-pasting numbers from the WHOOP app.

Part of Delx Wellness, a registry of local-first wellness MCP connectors.

> If this connector helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.

Why this exists

WHOOP gives you rich physiology — recovery score, HRV, sleep stages, strain — but it lives behind an OAuth API and a closed app. Bringing it into your AI agent today means writing the OAuth dance yourself, storing tokens safely, normalizing responses and handling pagination.

This package does all of that locally, exposes WHOOP through the Model Context Protocol, and lets any MCP-compatible agent read your WHOOP context with one config snippet. Tokens never leave your machine.

Setup in 60 seconds

You'll need a WHOOP Developer app (create one here) with redirect URI http://127.0.0.1:3000/callback.

npx -y whoop-mcp-unofficial setup    # interactive: paste client id + secret
npx -y whoop-mcp-unofficial auth     # opens browser, captures the OAuth code
npx -y whoop-mcp-unofficial doctor   # verifies you're ready

Then add this to your MCP client config:

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["-y", "whoop-mcp-unofficial"]
    }
  }
}

For Claude Desktop, run setup --client claude and the snippet is written for you.

Try it with your agent

Three things to ask first:

Use whoop_connection_status to check setup, then run whoop_daily_summary.
Give me a 5-line operating brief for today.

Call whoop_weekly_summary with response_format=json. Identify the top
bottleneck and give me a sleep + training plan for next week.

Use the whoop_daily_performance_coach prompt. Focus on whether I should train
hard today.

Data availability

This package uses the official WHOOP OAuth API (v2). It does not access raw device sensor streams.

| Data | Available | Notes |
|---|:---:|---|
| Recovery score, HRV, RHR, SpO2, skin temp | ✓ | When WHOOP returns a scored recovery |
| Sleep sessions + stages + performance | ✓ | All scored sleep records |
| Cycles + day strain + kilojoules | ✓ | Physiological cycles |
| Workouts + sport + heart-rate zones | ✓ | All recorded workouts |
| Profile + body measurements | ✓ | Height, weight, max HR |
| Continuous heart-rate / device telemetry | — | Not exposed by WHOOP's public API |
| Live BLE heart-rate listening | — | This package is not a Bluetooth listener |

When this README says raw, it means the upstream WHOOP API JSON for a supported endpoint — not raw sensor samples.

Tools

Start with these:

- whoop_connection_status — verify local setup before calling WHOOP
- whoop_daily_summary — readiness, sleep, load and action candidates for today
- whoop_weekly_summary — scorecard, comparison vs prior week, next-week plan

Auth & diagnostics

- whoop_capabilities, whoop_agent_manifest, whoop_privacy_audit, whoop_cache_status
- whoop_get_auth_url, whoop_exchange_code, whoop_revoke_access

Profile

- whoop_get_profile, whoop_get_body_measurements

Collections (paginated, with start/end filters and privacy-mode override)

- whoop_list_recoveries, whoop_list_sleeps, whoop_list_cycles, whoop_list_workouts

Common collection params: start, end, limit (max 25), next_token, all_pages, max_pages, response_format (markdown/json), privacy_mode (summary/structured/raw).

Single records by id

- whoop_get_cycle, whoop_get_sleep, whoop_get_workout
- whoop_get_cycle_sleep, whoop_get_cycle_recovery

Prompts

- whoop_daily_performance_coach — practical daily plan from today's signals
- whoop_weekly_training_review — week comparison + next-week plan
- whoop_sleep_recovery_investigator — investigate sleep ↔ recovery patterns

Each accepts timezone (IANA, default UTC).

Resources

- whoop://capabilities
- whoop://summary/daily, whoop://summary/weekly
- whoop://latest/recovery, whoop://latest/sleep, whoop://latest/cycle

Privacy & security

- OAuth tokens are stored in ~/.whoop-mcp/tokens.json with 0600 permissions and are never returned by tools.
- Refresh-token rotation uses a lock file to avoid concurrent refresh races.
- whoop_revoke_access is the only destructive tool — it deletes local tokens and revokes the grant.
- WHOOP_PRIVACY_MODE defaults to structured. Raw WHOOP API payloads are opt-in via raw mode or per-call override.
- The MCP client never sees access or refresh tokens.
- This is not medical advice. The server exposes user-authorized data for personal AI workflows, not diagnosis or treatment.

Configuration

setup writes most of these into ~/.whoop-mcp/config.json (0600). Manual env override is supported:

WHOOP_CLIENT_ID=…
WHOOP_CLIENT_SECRET=…
WHOOP_REDIRECT_URI=http://127.0.0.1:3000/callback
Optional
WHOOP_SCOPES="read:recovery read:cycles read:workout read:sleep read:profile read:body_measurement"
WHOOP_PRIVACY_MODE=structured        # summary | structured | raw
WHOOP_CACHE=sqlite                   # optional read-through cache
WHOOP_TOKEN_PATH=~/.whoop-mcp/tokens.json
WHOOP_CACHE_PATH=~/.whoop-mcp/cache.sqlite

Hermes / remote setup

npx -y whoop-mcp-unofficial setup --client hermes --no-auth
npx -y whoop-mcp-unofficial auth                       # run locally if browser auth is needed
npx -y whoop-mcp-unofficial doctor --client hermes
hermes mcp test whoop

After Hermes config changes, use /reload-mcp or hermes mcp test whoop. Don't restart the gateway for normal data access.

If browser OAuth has to happen on a different machine than Hermes, run auth locally and copy ~/.whoop-mcp/tokens.json to the server with chmod 600.

Requirements

- Node.js 20+
- A WHOOP Developer app with redirect URI http://127.0.0.1:3000/callback

Default OAuth scopes:

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

Development

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

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

Docs

- Quickstart
- Privacy model
- FAQ
- Resources & prompts
- Roadmap

Links

- npm: <https://www.npmjs.com/package/whoop-mcp-unofficial>
- Docs site: <https://wellness.delx.ai/connectors/whoop>
- Legacy docs: <https://whoopmcp.vercel.app/>
- GitHub Pages mirror: <https://davidmosiah.github.io/whoop-mcp/>
- Delx Wellness registry: <https://github.com/davidmosiah/delx-wellness>
- Connector quality standard: <https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md>
- Official WHOOP API docs: <https://developer.whoop.com/api/>

License

MIT — see LICENSE.

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.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

whoop_data_inventory

whoop_capabilities

whoop_agent_manifest

whoop_quickstart

whoop_demo

whoop_profile_get

whoop_profile_update

whoop_onboarding

whoop_get_auth_url

whoop_exchange_code

whoop_get_profile

whoop_get_body_measurements

whoop_list_cycles

whoop_list_recoveries

whoop_list_sleeps

whoop_list_workouts

whoop_connection_status

whoop_cache_status

whoop_privacy_audit

whoop_revoke_access

whoop_daily_summary

whoop_weekly_summary

whoop_recovery_trend

whoop_sleep_trend

whoop_wellness_context

whoop_get_cycle

whoop_get_sleep

whoop_get_workout

whoop_get_cycle_sleep

whoop_get_cycle_recovery

Claude Desktop / Cursor

McpServers

whoop-mcp-server

Why this exists

Setup in 60 seconds

Try it with your agent

Data availability

Tools

Prompts

Resources

Privacy & security

Configuration

Optional

Hermes / remote setup

Requirements

Development

Docs

Links

License

Disclaimer

Install

More like this

Sentry

Github

Git

GitLab

Context 7

1Panel

`whoop_data_inventory`

`whoop_capabilities`

`whoop_agent_manifest`

`whoop_quickstart`

`whoop_demo`

`whoop_profile_get`

`whoop_profile_update`

`whoop_onboarding`

`whoop_get_auth_url`

`whoop_exchange_code`

`whoop_get_profile`

`whoop_get_body_measurements`

`whoop_list_cycles`

`whoop_list_recoveries`

`whoop_list_sleeps`

`whoop_list_workouts`

`whoop_connection_status`

`whoop_cache_status`

`whoop_privacy_audit`

`whoop_revoke_access`

`whoop_daily_summary`

`whoop_weekly_summary`

`whoop_recovery_trend`

`whoop_sleep_trend`

`whoop_wellness_context`

`whoop_get_cycle`

`whoop_get_sleep`

`whoop_get_workout`

`whoop_get_cycle_sleep`

`whoop_get_cycle_recovery`