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.

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.

🎥 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