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)

Quick Comparison (WHOOP MCP packages on npm)

Based on npm search results for whoop mcp on 2026-05-30.

| Package | Latest version | Last publish (UTC) | MCP Registry | Runtime deps | npm | |------|-----------------|--------------------|----|--------------|-----| | whoop-ai-mcp (this repo) | 0.4.0 | 2026-05-31 | ✅ io.github.shashankswe2020-ux/whoop | 2 | https://www.npmjs.com/package/whoop-ai-mcp | | whoop-mcp-unofficial | 0.4.5 | 2026-05-29 | — | 5 | https://www.npmjs.com/package/whoop-mcp-unofficial | | @nchemb/whoop-mcp | 0.2.0 | 2026-04-27 | — | 4 | https://www.npmjs.com/package/@nchemb/whoop-mcp | | @scom82/whoop-mcp | 0.1.0 | 2026-05-17 | — | 1 | https://www.npmjs.com/package/@scom82/whoop-mcp | | whoop-mcp-server | 0.0.5 | 2026-03-13 | — | 2 | https://www.npmjs.com/package/whoop-mcp-server | | whoop-mcp | 0.1.2 | 2026-03-11 | — | 2 | https://www.npmjs.com/package/whoop-mcp | | @roebot0/whoop-mcp | 1.0.0 | 2026-04-06 | — | 3 | https://www.npmjs.com/package/@roebot0/whoop-mcp | | @alacore/whoop-mcp-server | 1.0.1 | 2025-10-09 | — | 2 | https://www.npmjs.com/package/@alacore/whoop-mcp-server |

Why this package stands out

• Published to npm and the official MCP Registry (via mcpName metadata)
• Most feature-rich standalone server: 14 tools + 4 resources + 5 prompts + analytics + auto-pagination
• Only 2 runtime dependencies (lightest footprint among full-featured options)
• No external infrastructure required (no SQLite, no Express, no relay servers)

Deep comparison ratings (WHOOP MCP packages on npm)

Evidence basis: npm registry metadata + npm-hosted README signals + package manifest fields (dependencies, repository, mcpName) collected on 2026-05-30.

Scoring dimensions (0–5):

• Security & resilience (35%): documented OAuth, token refresh, retry/backoff, secure token file permissions (0600), no shared relay
• Freshness (25%): recency of latest npm publish
• Docs & verification signals (25%): README coverage for OAuth, testing, changelog/release notes, and MCP Inspector usage
• Discoverability & portability (15%): MCP Registry metadata (mcpName), repository metadata present, lean runtime dependency count, no external infra required

Ratings are documentation/metadata-driven and are not a source-code security audit.

| Package | Security & resilience | Freshness | Docs & verification | Discoverability | Overall | Key differentiator / gap vs whoop-ai-mcp | |------|------------------------|-----------|---------------------|-----------------|--------------------|-------------------------------------| | whoop-ai-mcp (this repo) | 5.0/5 | 5.0/5 | 5.0/5 | 5.0/5 | 5.0/5 | Baseline — MCP Registry, 2 deps, analytics, no external infra | | whoop-mcp-unofficial | 4.5/5 | 5.0/5 | 4.0/5 | 3.5/5 | 4.3/5 | Strong feature set (20+ tools, SQLite cache, privacy modes); heavier deps (5: express, better-sqlite3, cors); no mcpName; part of "Delx Wellness" ecosystem | | @nchemb/whoop-mcp | 3.0/5 | 4.0/5 | 3.5/5 | 2.5/5 | 3.2/5 | Unique shared OAuth relay (no dev app needed); local SQL queries; capped at 10 test users; 4 deps; no mcpName | | whoop-mcp-server | 3.8/5 | 3.0/5 | 2.5/5 | 3.3/5 | 3.1/5 | No mcpName; no Inspector/changelog signal; older publish cadence | | @scom82/whoop-mcp | 2.0/5 | 4.5/5 | 2.0/5 | 2.0/5 | 2.5/5 | Requires self-hosted FastAPI backend (whoop-web); not standalone; 1 dep but external infra needed | | @roebot0/whoop-mcp | 2.5/5 | 4.0/5 | 1.3/5 | 1.7/5 | 2.4/5 | No 0600 docs; no mcpName; no explicit testing/changelog signal | | @alacore/whoop-mcp-server | 2.5/5 | 2.0/5 | 2.5/5 | 3.3/5 | 2.5/5 | Older publish cadence; no mcpName; retry/backoff not documented | | whoop-mcp | 0.0/5 | 3.0/5 | 0.0/5 | 3.3/5 | 1.3/5 | OAuth/refresh/retry not documented; no mcpName |

🎥 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 claude mcp add command for Claude Code) and verifies your WHOOP credentials in one go:

npx whoop-ai-mcp setup

Flags: