whoop-mcp is a local-first MCP (Model Context Protocol) server used to connect AI agents to the user's WHOOP recovery, sleep, strain, and HRV data. It is aimed at users using Claude, Cursor, Hermes, OpenClaw, or other MCP-compatible agents, with the goal of letting agents think about training, sleep, and recovery without copying and pasting numbers from the WHOOP App. This project is unofficial, is not affiliated with, endorsed by, or supported by WHOOP, Inc., and is limited to users using their own WHOOP account and complying with the WHOOP developer terms.
Purpose and positioning WHOOP provides rich physiological data—recovery scores, HRV, sleep stages, strain—but this data sits behind an OAuth API and a closed app. To connect it to an AI agent, you usually need to implement the OAuth flow yourself, securely store tokens, normalize responses, and handle pagination. whoop-mcp does this work locally, exposes WHOOP data through MCP, and allows any MCP-compatible agent to read WHOOP context through a configuration snippet. Tokens never leave the user's machine.
Main capabilities The server provides the following categories of tools and resources:
- Data availability and onboarding: whoop_demo (synthetic recovery/sleep/strain data without OAuth, marked with is_demo: true), whoop_connection_status (verify local setup before calling WHOOP), whoop_data_inventory (inventory supported data domains, permission scopes, privacy modes, and recommended first calls, without calling the WHOOP API).
- Summaries: whoop_daily_summary (readiness, sleep, strain, and action candidates for the day), whoop_weekly_summary (scorecard, comparison with the previous week, plan for the next week).
- Authentication and diagnostics: whoop_capabilities, whoop_agent_manifest, whoop_privacy_audit, whoop_cache_status, whoop_get_auth_url, whoop_exchange_code, whoop_revoke_access, whoop_get_profile, whoop_get_body_measurements.
- Collections (paginated, supporting start/end filtering and privacy mode overrides): whoop_list_recoveries, whoop_list_sleeps, whoop_list_cycles, whoop_list_workouts. Common parameters include start, end, limit (maximum 25), next_token, all_pages, max_pages, response_format (markdown/json), privacy_mode (summary/structured/raw).
- Single-record queries: whoop_get_cycle, whoop_get_sleep, whoop_get_workout, whoop_get_cycle_sleep, whoop_get_cycle_recovery.
- Scenario-oriented tools: whoop_daily_performance_coach (gives a practical daily plan based on the day's signals), whoop_weekly_training_review (week comparison and plan for the next week), whoop_sleep_recovery_investigator (studies sleep and recovery patterns). Each tool accepts a time zone parameter (IANA, default UTC).
- Resources: whoop://capabilities, whoop://summary/daily, whoop://summary/weekly, whoop://latest/recovery, whoop://latest/sleep, whoop://latest/cycle.
How to use Installation: you can install with the one-command Delx Wellness for Hermes installation: npx -y delx-wellness-hermes setup—it preconfigures this connector and the full Delx Wellness stack in a dedicated Hermes profile. It can also be connected independently to Claude Desktop / Cursor / ChatGPT Desktop. For Claude Desktop, run setup --client claude and the configuration snippet will be written automatically. It uses stdio transport by default; optional Streamable HTTP (no session id, JSON responses, loopback only) is available with the environment variables WHOOP_MCP_HOST, WHOOP_MCP_PORT, WHOOP_MCP_TRANSPORT=http. Setup requires the user to create a WHOOP developer app, with the redirect URI being http://127.0.0.1:3000/callback。OAuth Tokens are stored in ~/.whoop-mcp/tokens.json (0600 permissions), and 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 authorization. WHOOP_PRIVACY_MODE defaults to structured, and raw WHOOP API payloads require opting in via raw mode or a per-call override. The demo-capture tool for demo capture can generate privacy-redacted transcripts for README demos, issue updates, or agent evaluations, and fails safely when setup is incomplete; the redactor blocks OAuth secrets, local token paths, raw payloads, exact recovery numbers, and exact sleep details.
Applicable scenarios and limitations It is intended for individual users who want to let AI agents combine their own WHOOP recovery, sleep, strain, and HRV data to assist with training, sleep, and recovery decisions. Limitations include: it uses the official WHOOP OAuth API (v2) and does not access raw device sensor streams; raw in the README refers to upstream WHOOP API JSON from supported endpoints, not raw sensor samples; it requires the user's own WHOOP developer app and account; it is an unofficial project and is not affiliated with WHOOP, Inc.; the software is provided as is, is not a medical device, does not provide medical advice, and must not be used for diagnosis or treatment; information such as platform support, fees, and pricing is not currently provided.
The project was built by David Mosiah and is part of Delx Wellness (a local-first health MCP connector registry). It builds on Shashank Mishra's earlier WHOOP MCP work, including the OAuth/WHOOP API direction and the earlier MIT-licensed whoop-ai-mcp package. MIT licensed, see LICENSE for details.
