Skip to main content
Glama

WHOOP MCP Server

Ein MCP (Model Context Protocol) Server, mit dem Claude Ihre persönlichen WHOOP-Gesundheitsdaten abfragen kann – Erholung, Schlaf, Belastung, Workouts und Profil – über WHOOPs offizielle OAuth 2.0 REST API (v2).

Jeder Benutzer führt eine eigene Kopie für sein eigenes WHOOP-Konto aus: Sie registrieren Ihre eigene kostenlose Entwickler-App bei WHOOP, und Ihre Tokens/Anmeldedaten verbleiben in lokalen Dateien auf Ihrem Rechner (gitignoriert) – es wird nichts geteilt oder irgendwohin gesendet, außer direkt zwischen Ihrem Rechner und der WHOOP-API.

git clone https://github.com/vaibhavgoel63-arch/Whoop-MCP.git
cd Whoop-MCP

1. WHOOP-API-Anmeldedaten abrufen

  1. Gehen Sie zum WHOOP Developer Dashboard und melden Sie sich an.

  2. Erstellen (oder öffnen) Sie eine App.

  3. Setzen Sie unter den API-Einstellungen der App den Redirect URI genau auf:

    http://localhost:8080/callback
  4. Kopieren Sie die Client ID und den Client Secret – Sie fügen diese in Schritt 3 unten in .env ein.

Related MCP server: whoop-mcp

2. Voraussetzungen

  • Node.js 18+ (erforderlich für die integrierte fetch-API). Überprüfen mit node --version.

3. Installieren und konfigurieren

npm install
cp .env.example .env

Öffnen Sie .env und fügen Sie Ihre Client ID und Ihren Client Secret aus Schritt 1 ein:

WHOOP_CLIENT_ID=your-client-id-here
WHOOP_CLIENT_SECRET=your-client-secret-here
WHOOP_REDIRECT_URI=http://localhost:8080/callback

⚠️ Sie müssen WHOOP_CLIENT_ID und WHOOP_CLIENT_SECRET manuell ausfüllen – der Server wird den OAuth-Flow nicht starten, bis diese gesetzt sind.

4. Erstellen und anmelden (einmalig)

npm run build
npm run login

Dies wird:

  1. Einen temporären lokalen Server auf http://localhost:8080 starten.

  2. Ihren Browser zum WHOOP-Zustimmungsbildschirm öffnen (der die Bereiche Erholung, Schlaf, Zyklus, Workout, Profil, Körpermaße und Offline/Aktualisierung anfordert).

  3. Nach Ihrer Zustimmung leitet WHOOP zurück zu localhost:8080/callback mit einem Autorisierungscode.

  4. Das Skript tauscht diesen Code gegen ein Access + Refresh Token aus und speichert sie in token.json (gitignoriert) im Projektstammverzeichnis.

Sie müssen dies nur einmal tun. Der MCP-Server aktualisiert das Access-Token automatisch mit dem Refresh-Token, wenn es abläuft (WHOOP-Access-Tokens halten etwa 1 Stunde). Wenn Ihr Refresh-Token jemals widerrufen wird oder abläuft, führen Sie einfach npm run login erneut aus.

5. Mit Claude Desktop verbinden

Öffnen Sie Ihre Claude Desktop-Konfigurationsdatei:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Hinweis: Wenn Sie Claude Desktop aus dem Microsoft Store installiert haben, könnte die obige Datei nur ein Platzhalter sein – die App liest tatsächlich %LOCALAPPDATA%\Packages\<Claude-Paketordner>\LocalCache\Roaming\Claude\claude_desktop_config.json. Wenn Tools nach den folgenden Schritten nicht angezeigt werden, überprüfen Sie dort.

Fügen Sie einen whoop-Eintrag unter mcpServers hinzu. Ersetzen Sie den unten stehenden Pfad durch den absoluten Pfad zu dist/server.js dieses Projekts auf Ihrem Rechner (finden Sie ihn mit pwd auf macOS/Linux oder cd auf Windows innerhalb des Projektordners):

{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp/dist/server.js"]
    }
  }
}

⚠️ Sie müssen diesen absoluten Pfad manuell ausfüllen zu dem Ort, an den Sie dieses Repository geklont haben. Verwenden Sie auch unter Windows Schrägstriche (z.B. C:/Benutzer/Sie/whoop-mcp/dist/server.js) – sie funktionieren in dieser JSON-Datei einwandfrei.

Starten Sie Claude Desktop dann vollständig neu (beenden Sie es über das System-Tray, schließen Sie nicht nur das Fenster).

6. Testen

  1. Klicken Sie in Claude Desktop auf das Werkzeug/Hammer-Symbol im Chatfeld und bestätigen Sie, dass Sie whoop mit 6 gelisteten Tools sehen: get_recovery, get_sleep, get_strain, get_workouts, get_profile, get_training_recommendation.

  2. Probieren Sie diese Aufforderungen:

    • "Wie war meine Erholung diese Woche?"

    • "Sollte ich heute hart trainieren?"

    • "Wie habe ich die letzten 3 Nächte geschlafen?"

    • "Zeig mir meine Workouts der letzten 7 Tage."

    • "Was ist meine aktuelle Belastung und wie vergleicht sie sich mit gestern?"

    • "Was war meine durchschnittliche Belastung im März 2026?" (historischer Bereich, nicht nur "letzte N Tage")

  3. Überprüfen Sie ein Ergebnis stichprobenartig (z.B. den heutigen Erholungswert) gegen die WHOOP-App, um sicherzustellen, dass die Zahlen übereinstimmen.

Tool-Referenz

Tool

Beschreibung

get_recovery(Tage | Start+Ende)

Erholungswert, HRV, Ruhepuls, SpO2, Hauttemperatur – plus eine Zusammenfassung der Durchschnittswerte

get_sleep(Tage | Start+Ende)

Schlafleistung %, Effizienz % und Phasenaufschlüsselung (Leicht/Tief/REM) – plus eine Zusammenfassung der Durchschnittswerte

get_strain(Tage | Start+Ende)

Tägliche Belastung, durchschnittliche/maximale Herzfrequenz, Kalorien pro Tag – plus eine Zusammenfassung der Durchschnitts-/Gesamtwerte

get_workouts(Tage | Start+Ende)

Protokollierte Workouts mit Sportart, Dauer, Belastung, Herzfrequenz, Kalorien – plus eine Zusammenfassung

get_profile()

Name, E-Mail, Größe, Gewicht, maximale Herzfrequenz

get_training_recommendation()

Kombiniert die heutige Erholung + die letzten 3 Schlafnächte zu einer grünen/gelben/roten Trainingsempfehlung, mit einer Schlafdefizit-Warnung, wenn die Leistung 2+ Nächte unter 80 % lag

Die vier bereichsbasierten Tools akzeptieren entweder days (gleitendes Fenster, z.B. days=7 für die letzte Woche) oder ein explizites Paar aus start/end-Datum (YYYY-MM-DD, Ende exklusiv) zum Abfragen eines bestimmten historischen Zeitraums, z.B. start="2026-03-01", end="2026-04-01" für den gesamten März 2026. Jedes gibt ein summary-Objekt (Durchschnitte/Gesamtsummen) zusammen mit den einzelnen täglichen/nächtlichen records zurück.

Fehlerbehebung

  • "Keine WHOOP-Tokens gefunden" – führen Sie npm run login aus.

  • 401 / Token-Fehler, nachdem es vorher funktioniert hat – der Server aktualisiert Access-Tokens automatisch; wenn Sie einen Aktualisierungsfehler sehen, wurde Ihr Refresh-Token wahrscheinlich widerrufen (z.B. haben Sie den App-Zugriff in den WHOOP-Einstellungen entfernt). Führen Sie npm run login erneut aus.

  • 403 Verboten – Ihrem Token fehlt ein Bereich. Bereiche werden bei der Anmeldung festgelegt, führen Sie also npm run login erneut aus, um ein neues Token mit dem vollständigen Bereichssatz zu erhalten.

  • 429 Zu viele Anfragen – Sie haben das WHOOP-Ratenlimit erreicht (100 Anfragen/Minute, 10.000/Tag). Warten Sie und versuchen Sie es erneut.

  • Tools werden in Claude Desktop nicht angezeigt – überprüfen Sie den absoluten Pfad in claude_desktop_config.json, dass Sie npm run build ausgeführt haben (die Konfiguration zeigt auf dist/server.js, nicht auf src/server.ts), und dass Sie Claude Desktop vollständig neu gestartet haben.

Projektstruktur

src/
  auth.ts        # OAuth constants, token load/save, refresh logic
  login.ts        # One-time login script (npm run login)
  whoopClient.ts  # Authenticated WHOOP API client + response normalizers
  server.ts       # MCP server exposing the 6 tools
.env.example      # Template for WHOOP_CLIENT_ID / WHOOP_CLIENT_SECRET / WHOOP_REDIRECT_URI

.env (Anmeldedaten) und token.json (Access/Refresh-Tokens) sind beide gitignoriert – committen Sie niemals eine der beiden Dateien.

Available Tools

6 tools
get_profileA

Get the WHOOP user's basic profile: name, email, height (cm), weight (kg), and max heart rate. Use this for identity or body-metric questions.

Inputs: no named parameters.

get_recoveryA

Get WHOOP recovery data: recovery score (0-100), HRV (ms), resting heart rate, SpO2, and skin temperature, per day. Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages plus the daily records. Use this to answer questions about how recovered/rested the user is, now or in the past.

Inputs: end, days, start.

get_sleepA

Get WHOOP sleep data: sleep performance %, efficiency %, time in bed, time asleep, and a breakdown of light/deep/REM sleep stages, per night (excludes naps). Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages plus the nightly records. Use this to answer questions about sleep quality or duration, now or in the past.

Inputs: end, days, start.

get_strainA

Get WHOOP daily strain data: cardiovascular strain score (0-21), average/max heart rate, and calories burned, per day (cycle). Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary with averages/totals plus the daily records. Use this to answer questions about daily exertion or workload, now or in the past — including things like 'what was my average strain in March'.

Inputs: end, days, start.

get_training_recommendationA

Get a coaching recommendation for today based on today's WHOOP recovery score and the last 3 days of sleep performance. Returns a recovery band (green/yellow/red) with guidance on training load, plus a warning if sleep debt has been building. Use this to answer 'should I train today' or 'how hard should I push today' style questions.

Inputs: no named parameters.

get_workoutsA

Get a list of logged WHOOP workouts, each with sport type, duration, strain, average/max heart rate, and calories burned. Accepts either the last N days or an explicit historical start/end range (e.g. a specific past month). Returns a summary plus the individual workout records. Use this to answer questions about specific exercise sessions, now or in the past.

Inputs: end, days, start.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool addresses a distinct WHOOP domain (recovery, sleep, strain, workouts, profile, training recommendation) with no overlap. The descriptions clearly differentiate the data each returns, making it easy for an agent to select the correct tool for a given question.

    Naming Consistency4/5

    All tool names follow a consistent 'get_' prefix with a noun representing the data type (recovery, sleep, strain, etc.). This is predictable and clear. The only minor deviation is the slightly longer 'get_training_recommendation' compared to the others, but it still fits the pattern.

    Tool Count5/5

    With 6 tools, the set is well-scoped for a WHOOP fitness tracker integration. Each tool represents a core data category a user would query, and there are no extraneous or missing tools that would make the surface too large or too small for the domain.

    Completeness4/5

    The tools cover the most common queries about WHOOP data: recovery, sleep, strain, workouts, profile, and training recommendations. A minor gap is the lack of tools to query cycle/physiological data, meal logging, or team features, but the core personal health metrics are well represented.

    Related MCP Connectors

    Related MCP Servers