whoop-ai-mcp

= 20">

An MCP (Model Context Protocol) server that connects AI assistants like Claude to your WHOOP health and fitness data. Ask questions about your recovery, sleep, workouts, and more — all through natural conversation.

📦 Published on the MCP Registry as io.github.shashankswe2020-ux/whoop — discoverable by any MCP-compatible client.

Features

• 🏋️ 14 health data tools — recovery, sleep, workouts, cycles, body measurements, profile, weekly summaries, trend analysis, period comparisons, individual record lookups, today's snapshot, and calendar grid
• 📊 4 MCP Resources — ambient health context (latest recovery, sleep, cycle, profile) available without explicit tool calls
• 💬 5 MCP Prompts — guided conversation starters for common health queries
• 📅 Rich natural date expressions — use "last 7 days", "this week", "last 2 weeks", "last 3 months", "this quarter", "last year", "2026-05", and more
• 📈 Built-in analytics — weekly summaries, trend detection (linear regression), and period comparisons computed server-side
• 🔐 Secure OAuth2 — browser-based authentication with automatic token refresh
• 🔄 Resilient — automatic retry on rate limits, token refresh on expiry, auto-pagination, clear error messages
• 💾 Secure token storage — tokens stored at ~/.whoop-mcp/tokens.json with 0600 permissions
• ⚡ Zero config — just add your WHOOP app credentials and go
• 📦 Lightweight — only two runtime dependencies (@modelcontextprotocol/sdk + zod)

SOTA scan (WHOOP MCP packages on npm)

Registry snapshot collected 2026-08-30. Versions and publish dates can change; this is an ecosystem comparison, not a source-code security audit.

Findings

• MCP Registry discoverability is now table stakes: at least three alternatives also publish mcpName identities.
• The leading portability trade-off remains local-first/no-infrastructure operation versus richer remote hosting, caching, or relay features.
• Current best practice is to document security controls, test/verification commands, provenance or SBOM metadata, and the exact transport/auth model. This project provides the first two and supports both local stdio and authenticated Streamable HTTP; it does not claim to be a security audit.

Why this package stands out

• 14 domain and analytical tools, 4 ambient resources, and 5 prompts in one standalone package.
• No database, relay service, or framework runtime dependency; only the MCP SDK and Zod are required.
• Published to npm and the official MCP Registry, with documented OAuth, token refresh, retries, caching, HTTP hardening, and Inspector verification.

Evidence and reproducibility: package names, versions, publish dates, dependency counts, descriptions, and mcpName values come from the npm Registry search and package manifests. Feature notes were checked against each package's published metadata/README where available. Re-run the scan with:

curl -s 'https://registry.npmjs.org/-/v1/search?text=whoop%20mcp&size=20'

🎥 Video Walkthrough

Watch a detailed walkthrough of setting up and using whoop-ai-mcp with Claude Desktop:

Covers: creating a WHOOP Developer App, configuring Claude Desktop, OAuth authentication, and querying your health data through natural conversation.

Prerequisites

1. A WHOOP account with an active membership
2. A WHOOP Developer App — create one at developer.whoop.com
   • Set the redirect URI to http://localhost:3000/callback
3. Node.js >= 20

Get a WHOOP

Don't have a WHOOP yet? Here's how to get started:

• 🛒 Buy a WHOOP on Amazon — WHOOP peak on Amazon
• 🔗 Join WHOOP directly — whoop.com/membership

Quickstart (MCP Registry)

This server is published on the official MCP Registry. MCP clients that support the registry can discover and install it automatically:

Server name: io.github.shashankswe2020-ux/whoop

You can also browse it via the registry API:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.shashankswe2020-ux/whoop"

Quickstart (Claude Desktop)

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "npx",
      "args": ["whoop-ai-mcp"],
      "env": {
        "WHOOP_CLIENT_ID": "your_client_id",
        "WHOOP_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Replace your_client_id and your_client_secret with the credentials from your WHOOP Developer App.

On first launch, a browser window will open for you to authorize access to your WHOOP data. After authorizing, tokens are cached locally and refresh automatically.

Then ask Claude something like:

"How am I doing today?"

"Show me my sleep data from the last 3 days"

"What workouts did I do this month?"

"Is my HRV trending up or down?"

"Give me a weekly health summary"

"Show me my recovery calendar for last 2 weeks"

whoop-mcp connected in Claude Desktop:

Chatting with WHOOP data through Claude:

Weekly Health Report demo (Claude Desktop):

Installation

Via npx (recommended)

No installation needed — Claude Desktop runs it automatically with the config above.

Global install

npm install -g whoop-ai-mcp

From source

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

Setup wizard (whoop-ai-mcp setup)

For a guided installation that writes the Claude Desktop config (or prints the registration command for Claude Code, Codex, or GitHub Copilot) and verifies your WHOOP credentials in one go:

npx whoop-ai-mcp setup

Flags:

• --client=claude-desktop (default) writes/merges claude_desktop_config.json with an automatic .bak backup.
• --client=claude-code prints the equivalent claude mcp add command.
• --client=codex prints the equivalent codex mcp add command (registers the server in ~/.codex/config.toml).
• --client=copilot prints the equivalent code --add-mcp command for GitHub Copilot in VS Code.
• --verify runs the OAuth flow end-to-end and fetches your profile to confirm everything is wired correctly before exiting.
• --client-id / --client-secret skip the interactive prompts (useful for scripts; secrets entered interactively are masked).

If WHOOP_CLIENT_ID and WHOOP_CLIENT_SECRET are already exported in your shell, the wizard uses them automatically — no prompts. Combine with --verify to do a one-shot config-correctness check:

WHOOP_CLIENT_ID=... WHOOP_CLIENT_SECRET=... npx whoop-ai-mcp setup --verify

If the Claude Desktop config file already contains a whoop MCP entry from a previous setup, the wizard short-cir