{
  "markdown": "# mcp-server-whoop\n\n[![npm version](https://img.shields.io/npm/v/mcp-server-whoop.svg)](https://www.npmjs.com/package/mcp-server-whoop)\n[![CI](https://github.com/Yadheedhya06/mcp-server-whoop/actions/workflows/ci.yml/badge.svg)](https://github.com/Yadheedhya06/mcp-server-whoop/actions/workflows/ci.yml)\n[![CodeQL and secrets](https://github.com/Yadheedhya06/mcp-server-whoop/actions/workflows/security.yml/badge.svg)](https://github.com/Yadheedhya06/mcp-server-whoop/actions/workflows/security.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/Yadheedhya06/mcp-server-whoop/badge)](https://scorecard.dev/viewer/?uri=github.com/Yadheedhya06/mcp-server-whoop)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA local-first, read-only [Model Context Protocol](https://modelcontextprotocol.io/) 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.\n\n## Why this server\n\n- Standard MCP over stdio, usable by any client that supports local MCP servers\n- Local WHOOP OAuth flow with each user's own WHOOP developer application\n- Access and rotating refresh tokens remain on the user's machine\n- Five focused read-only tools instead of a noisy API dump\n- Per-record local timestamps, so travel does not shift sleep or workout dates\n- Explicit `processing` status, with no older recovery substituted while a new sleep is pending\n- Score-derived metrics appear only for `SCORED` records; live current-cycle strain is labeled `provisional_strain`\n- Human-scale hours, minutes, calories, and heart-rate-zone minutes\n- No raw identifiers, OAuth secrets, or raw continuous heart-rate claims in tool output\n- No hosted relay, telemetry, database, generic HTTP tool, raw SQL, or install lifecycle scripts\n- Reproducible tarball security audit, CycloneDX SBOM, CodeQL, Gitleaks, dependency review, and OpenSSF Scorecard\n\n> This is an independent community project. It is not affiliated with or endorsed by WHOOP. WHOOP data is useful coaching context, not medical advice.\n\n## Requirements\n\n- Node.js 18 or newer\n- A WHOOP account\n- A free application in the [WHOOP Developer Dashboard](https://developer.whoop.com/dashboard/)\n- An MCP-compatible AI client\n\n## Quick start\n\n1. Create a WHOOP developer application and register `http://127.0.0.1:8765/callback`.\n2. Enable the five read scopes and `offline` listed below.\n3. Run `npx -y mcp-server-whoop@0.2.2 auth` in a terminal and approve WHOOP access.\n4. Run `npx -y mcp-server-whoop@0.2.2 status` to confirm the local grant exists.\n5. Add the stdio command `npx -y mcp-server-whoop@0.2.2` to your AI client's MCP configuration.\n6. Restart or reload the client, then ask: `Use WHOOP to summarize my recovery and sleep from the last 7 days.`\n\nThe authorization command and the AI client must run as the same operating-system user, or both must set `WHOOP_CREDENTIALS_FILE` to the same private file. The package never asks you to paste WHOOP tokens into an AI conversation.\n\nThe 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.\n\n## 1. Create your WHOOP application\n\nCreate an application in the WHOOP Developer Dashboard and register this exact redirect URL:\n\n```text\nhttp://127.0.0.1:8765/callback\n```\n\nEnable these scopes:\n\n```text\noffline\nread:recovery\nread:cycles\nread:sleep\nread:workout\nread:body_measurement\n```\n\n`offline` is required because WHOOP access tokens expire and WHOOP rotates refresh tokens.\n\n## 2. Authorize locally\n\nRun:\n\n```bash\nnpx -y mcp-server-whoop@0.2.2 auth\n```\n\nThe 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.\n\nCredentials are stored at:\n\n```text\n~/.config/mcp-server-whoop/credentials.json\n```\n\nOn Linux and macOS, every path ancestor is checked before use, the direct directory is current-user-owned with mode `0700`, and the file is a single-link current-user-owned regular file with mode `0600`. Override the path with `WHOOP_CREDENTIALS_FILE` only when every ancestor is trusted and is not a symlink.\n\nPersistent OAuth credentials intentionally fail closed on native Windows. Node.js file modes do not enforce private Windows ACLs, and its standard file APIs cannot guarantee reparse-safe credential writes. Native Windows users can provide a short-lived `WHOOP_ACCESS_TOKEN` through the MCP process environment, but automatic authorization and refresh-token persistence require WSL, Linux, or macOS until a native credential backend is available.\n\nFor headless environments, provide `WHOOP_CLIENT_ID`, `WHOOP_CLIENT_SECRET`, and optionally `WHOOP_REDIRECT_URI` as environment variables before running `auth`.\n\nThe OAuth callback still needs to reach the machine running `auth`. When authorizing over SSH, create a loopback tunnel from your workstation first:\n\n```bash\nssh -L 8765:127.0.0.1:8765 user@your-server\n```\n\nThen run `auth` in that SSH session and open its printed WHOOP URL in your workstation browser. Do not pass the client secret as a command-line argument because shell history and process listings may expose it.\n\nCheck setup without displaying secrets:\n\n```bash\nnpx -y mcp-server-whoop@0.2.2 status\n```\n\nRemove the local grant:\n\n```bash\nnpx -y mcp-server-whoop@0.2.2 logout\n```\n\nRevoking access in WHOOP account settings is also recommended when you no longer use an integration.\n\n## 3. Add it to an AI client\n\n### Claude Desktop\n\nAdd this under `mcpServers` in Claude Desktop's configuration, then fully restart Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"whoop\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-whoop@0.2.2\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add --transport stdio whoop -- npx -y mcp-server-whoop@0.2.2\n```\n\n### Cursor, Windsurf, Gemini Code Assist, and other `mcpServers` clients\n\nAdd the server to the client's MCP JSON. Gemini Code Assist uses `~/.gemini/settings.json`; other clients choose their own settings path.\n\n```json\n{\n  \"mcpServers\": {\n    \"whoop\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-whoop@0.2.2\"]\n    }\n  }\n}\n```\n\n### VS Code\n\nCreate `.vscode/mcp.json` for a project, or use VS Code's **MCP: Add Server** command:\n\n```json\n{\n  \"servers\": {\n    \"whoop\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-server-whoop@0.2.2\"]\n    }\n  }\n}\n```\n\n### Codex\n\nEither run:\n\n```bash\ncodex mcp add whoop -- npx -y mcp-server-whoop@0.2.2\n```\n\nOr add this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.whoop]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-server-whoop@0.2.2\"]\n```\n\n### ChatGPT\n\nLocal Codex and ChatGPT desktop clients that support stdio can use the Codex configuration above. ChatGPT web does not launch a command on your computer; it requires a separately secured remote bridge or tunnel and a workspace plugin. This repository intentionally does not ship or operate a public health-data relay.\n\nClient menus and configuration paths change over time. If a client supports standard local stdio MCP, the portable values are always:\n\n```text\ncommand: npx\narguments: -y mcp-server-whoop@0.2.2\n```\n\n## Confirm the connection\n\nAfter restarting the client, confirm that it discovers exactly these five tools:\n\n```text\nwhoop_latest_overview\nwhoop_recovery_history\nwhoop_sleep_history\nwhoop_cycle_strain_history\nwhoop_workout_history\n```\n\nUseful prompts:\n\n- `Use WHOOP to review today's recovery, latest sleep, current strain, and latest workout.`\n- `Compare my recovery, HRV, and resting heart rate over the last 14 days.`\n- `Show my last 7 days of sleep, including naps, and flag anything still processing.`\n- `Summarize my workout strain and heart-rate zones for the last 30 days.`\n- `Use WHOOP as context for today's training, but do not treat it as medical advice.`\n\nThe model decides when to call tools, so explicitly say `Use WHOOP` when you want live data rather than a general answer.\n\n## Tools\n\n| Tool | Purpose |\n|---|---|\n| `whoop_latest_overview` | Current coaching snapshot with pending-data safeguards |\n| `whoop_recovery_history` | Recovery, HRV, resting HR, SpO2, and skin-temperature trends |\n| `whoop_sleep_history` | Primary sleep and optional naps, stages, need, quality, and timing |\n| `whoop_cycle_strain_history` | Daily strain, calories, and average/max heart rate |\n| `whoop_workout_history` | Sport, duration, strain, HR, calories, distance, and zone minutes |\n\nAll tools are marked read-only, non-destructive, and idempotent.\n\n### Why deliberately only five tools?\n\nFor a health-data MCP, a larger tool count also means a larger capability surface. This server keeps authentication outside the agent and gives the model only the five health-reading capabilities it needs.\n\nIt intentionally has:\n\n- no WHOOP write, revoke, token-management, or authorization-code tools\n- no profile/email/name scope\n- no raw-record, raw-ID, arbitrary endpoint, SQL, file, or shell tool\n- no hosted OAuth relay, telemetry service, health-data cache, or database\n- no stale-recovery fallback when the newest sleep is still processing\n\nThe goal is not maximum WHOOP API coverage. It is the smallest practical authority boundary for recovery-aware AI.\n\n## Data semantics\n\nWHOOP returns absolute timestamps plus a `timezone_offset` on sleep, cycle, and workout records. This server applies each record's own offset and returns only already-converted local timestamps such as:\n\n```text\n2026-07-07 18:02:22 +04:00\n```\n\nIt does not apply the machine's current timezone to historical records.\n\nWHOOP exposes activity type and workout sport, but its public API does not indicate whether a workout was auto-detected or manually started. This server does not guess.\n\nWhen the newest primary sleep is still `PENDING_SCORE`, the latest overview returns:\n\n```json\n{\n  \"status\": {\n    \"state\": \"waiting_for_whoop\",\n    \"current_recovery_available\": false\n  },\n  \"recovery\": null\n}\n```\n\nAn older recovery is never presented as current.\n\n## Environment variables\n\n| Variable | Purpose |\n|---|---|\n| `WHOOP_CLIENT_ID` | WHOOP OAuth client ID |\n| `WHOOP_CLIENT_SECRET` | WHOOP OAuth client secret |\n| `WHOOP_REDIRECT_URI` | OAuth callback, defaults to `http://127.0.0.1:8765/callback` |\n| `WHOOP_CREDENTIALS_FILE` | Override local credential-file path |\n| `WHOOP_ACCESS_TOKEN` | Optional short-lived access-token override |\n| `WHOOP_REFRESH_TOKEN` | Optional refresh-token override |\n| `WHOOP_TOKEN_EXPIRES_AT` | Optional ISO token-expiry override |\n\nClient configuration from `WHOOP_CLIENT_ID`, `WHOOP_CLIENT_SECRET`, and `WHOOP_REDIRECT_URI` overrides file values. Token environment variables can bootstrap a headless setup, but once a refresh token rotates, the newer token persisted in the credential file takes precedence. Do not put secrets directly in command-line arguments or commit them to source control.\n\n## Troubleshooting\n\n### `Missing WHOOP ...`\n\nRun `npx -y mcp-server-whoop@0.2.2 status` as the same OS user that launches the AI client. If the credentials are elsewhere, set `WHOOP_CREDENTIALS_FILE` in the client's MCP environment.\n\n### WHOOP reports a redirect mismatch\n\nThe redirect in the Developer Dashboard and the value used by this package must match exactly. The default is `http://127.0.0.1:8765/callback`, including scheme, host, port, and path.\n\n### The browser does not open\n\nCopy the authorization URL printed in the terminal and open it manually. The callback listener expires after five minutes; rerun `auth` if needed.\n\n### Port `8765` is already in use\n\nRegister another loopback URL such as `http://127.0.0.1:9876/callback`, set `WHOOP_REDIRECT_URI` to that exact value, and rerun `auth`.\n\n### Recovery is `null`\n\nCheck the returned `status.state`. If it is `waiting_for_whoop` or `waiting_for_recovery`, WHOOP has not finished scoring the newest sleep. The server intentionally refuses to label an older recovery as current; retry after WHOOP finishes processing.\n\n### The client shows no tools\n\nRun `npx -y mcp-server-whoop@0.2.2 --help` in a terminal to verify Node.js and npm can launch the package, then restart the AI client and inspect its MCP logs. Do not run the bare server interactively to inspect output: stdio is reserved for MCP protocol messages.\n\n## Development\n\n```bash\ngit clone git@github.com:Yadheedhya06/mcp-server-whoop.git\ncd mcp-server-whoop\nnpm ci --ignore-scripts\nnpm run check\n```\n\nRun the local source server:\n\n```bash\nnpm run dev\n```\n\nBuild and inspect the exact npm artifact:\n\n```bash\nnpm pack --dry-run\n```\n\n## Privacy and security\n\nThis project publishes evidence rather than claiming that any package is perfectly safe. See the full [security policy](SECURITY.md) and [reproducible security evidence](SECURITY-EVIDENCE.md).\n\n- Every user owns their WHOOP developer app and OAuth grant.\n- Credentials stay local and are never returned through MCP tools.\n- The package provides no WHOOP write, generic network, shell, filesystem, or raw API passthrough tool.\n- On supported POSIX storage, the credential file and every ancestor are checked against symlinks, unsafe ownership or permissions, oversized input, and unexpected fields. Refresh rotation uses a heartbeat lease that does not trust PIDs, an exclusive temporary file, atomic replacement, post-write verification, and disk sync. Native Windows persistence fails closed.\n- WHOOP and OAuth responses are size-bounded and structurally validated; provider response bodies are never copied into MCP errors.\n- Direct dependencies use exact versions. There are only two direct runtime dependencies and no package install lifecycle scripts.\n- CI runs the full test suite on Node 18, 20, 22, and 24, adds macOS and Windows platform-security jobs, audits both source and the exact compiled npm runtime, verifies npm registry signatures, and generates a CycloneDX SBOM.\n- Independent workflows run CodeQL, Gitleaks, dependency review, and OpenSSF Scorecard.\n- The publish workflow packs once and publishes that exact tarball through npm Trusted Publishing with Sigstore provenance. GitHub separately attests that tarball against its CycloneDX SBOM; no long-lived npm token is used.\n\nThese controls reduce risk, but they are not a paid penetration test or a guarantee. The limitations are documented explicitly in `SECURITY-EVIDENCE.md`.\n\n## License\n\nMIT\n",
  "bytes": 14501,
  "sha": "48390f082273463682554a5bcb8506d49a67b600ab2511f2c722b25631b7326a",
  "repo_slug": "yadheedhya06/mcp-server-whoop",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yadheedhya06_mcp_server_whoop_b6c0a089/readme"
}