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 Server

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

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.