8000 GitHub - Npab19/whoop-mcp: MCP server for the Whoop API with OAuth 2.1 · GitHub
[go: up one dir, main page]

Skip to content
Npab19Public

About

MCP server for the Whoop API with OAuth 2.1

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Whoop MCP Server

A Model Context Protocol server for the Whoop API with OAuth 2.1 authentication. Modeled after the Fitbit and Oura MCPs in this monorepo.

Gives Claude access to your Whoop recovery, strain, sleep, and workout data via 11 read-only tools.

Built With

Getting Started

Prerequisites

  • Docker and Docker Compose
  • A Whoop developer app with a client ID and secret
  • A publicly reachable HTTPS endpoint that forwards to this container on port 8000 (e.g. nginx + Let's Encrypt, ngrok, or Cloudflare Tunnel — your choice)

Whoop App Setup

  1. Go to developer-dashboard.whoop.com and create an app.
  2. Set the Redirect URI to https://<your-public-host>/whoop-callback (must match SERVER_URL below exactly).
  3. Enable these scopes:
    • offline (required to receive a refresh token)
    • read:recovery
    • read:cycles
    • read:workout
    • read:sleep
    • read:profile
    • read:body_measurement
  4. Note your Client ID and Client Secret.

Installation

  1. Clone the repo and cd into it.

  2. Copy the environment template:

    cp .env.example .env
  3. Fill in .env:

    WHOOP_CLIENT_ID=your_client_id
    WHOOP_CLIENT_SECRET=your_client_secret
    SERVER_URL=https://your-public-host.example.com
  4. Start the service:

    docker compose up -d

    The container listens on host port 8000. Put your own HTTPS reverse proxy in front so https://<your-public-host> reaches it.

Hosting examples

ngrok (quick test):

ngrok http 8000
# Use the https URL ngrok prints as your SERVER_URL.

nginx reverse proxy (sketch):

server {
  listen 443 ssl http2;
  server_name your-public-host.example.com;
  # ssl_certificate ...
  # ssl_certificate_key ...
  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
  }
}

Usage

Claude.ai Web Connectors

Connector URL:

https://<your-public-host>/mcp

OAuth runs automatically the first time you connect — you'll be redirected to Whoop to grant access.

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "whoop": {
      "type": "http",
      "url": "https://<your-public-host>/mcp"
    }
  }
}

Available Tools

Category Tools
Cycle get_cycle_collection, get_cycle_by_id, get_sleep_for_cycle
Recovery get_recovery_collection, get_recovery_for_cycle
Sleep get_sleep_collection, get_sleep_by_id
Workout get_workout_collection, get_workout_by_id
User get_profile_basic, get_body_measurement
Activity Mapping get_activity_v2_id (v1 → v2 ID lookup)

Collection tools accept limit (1-25), start, end (ISO-8601), and nextToken for pagination.

Token Persistence

Whoop tokens are persisted to /data/.whoop_tokens.json inside the container (backed by the whoop-data Docker volume), so authorization survives restarts. Whoop rotates refresh tokens on every refresh — both fields are written back to disk after each refresh.

Notes

  • All tools are read-only. The DELETE /v2/user/access endpoint is intentionally not exposed.
  • Webhooks are not implemented — Whoop's v1 webhooks were removed and v2 webhooks aren't part of this server.
  • Single-user: like Oura and Fitbit, this server stores one user's tokens.

About

MCP server for the Whoop API with OAuth 2.1

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0