whoop-mcp

Lokaler MCP-Server für die WHOOP API v2. Läuft vollständig auf dem eigenen Rechner: Recovery, Schlaf, Strain und Workouts stehen in Claude als Tools zur Verfügung, ein täglicher Sync legt eine lokale Historie an und schreibt einen JSON-Export fürs eigene Dashboard.

Was es kann

Tool	Zweck
whoop_summary	Kombinierter Tagesüberblick aus Recovery, Schlaf und Strain
whoop_recovery	Recovery Score, HRV, Ruhepuls, SpO2, Hauttemperatur
whoop_sleep	Dauer, Schlafphasen, Performance, Konsistenz, Atemfrequenz
whoop_cycles	Tages-Strain, Kalorien, Ø- und Maximalpuls
whoop_workouts	Trainings mit Strain, HF-Zonen, Distanz, Kalorien
whoop_body	Größe, Gewicht, maximale Herzfrequenz
whoop_history	Langzeitauswertung aus der lokalen Datenbank, mit Trendvergleich
whoop_sync	Daten abrufen, lokal speichern, Export schreiben

Einheiten werden alltagstauglich umgerechnet: Millisekunden zu Stunden, Kilojoule zu Kilokalorien, Meter zu Kilometern. Die Rohantworten bleiben in der Datenbank erhalten.

Voraussetzungen

Eine App im WHOOP Developer Dashboard mit dieser Redirect URL:

http://localhost:8765/callback

und diesen Scopes:

offline  read:recovery  read:cycles  read:sleep  read:workout
read:body_measurement  read:profile

offline ist zwingend erforderlich — ohne diesen Scope gibt WHOOP keinen Refresh Token heraus und die Verbindung müsste stündlich erneuert werden.

Installation

git clone https://github.com/d00ennis/whoop-mcp.git
cd whoop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Einrichtung

whoop-mcp setup     # Client ID und Secret hinterlegen (landen im Schlüsselbund)
whoop-mcp auth      # Browser öffnet sich, Zugriff einmal bestätigen
whoop-mcp sync      # erster Abruf, standardmäßig 90 Tage rückwirkend
whoop-mcp status    # Konfiguration und Datenbestand prüfen

In Claude einbinden

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "whoop": {
      "command": "/PFAD/ZU/whoop-mcp/.venv/bin/whoop-mcp",
      "args": ["serve"]
    }
  }
}

Danach Claude neu starten.

Täglicher Sync

Per launchd oder Cron, zum Beispiel jeden Morgen um 6:30 Uhr:

30 6 * * * /PFAD/ZU/whoop-mcp/.venv/bin/whoop-mcp sync >> ~/.whoop-mcp/sync.log 2>&1

Wo die Daten liegen

Was	Wo
Client ID, Secret, Tokens	macOS-Schlüsselbund (Dienst whoop-mcp)
Historie	~/.whoop-mcp/whoop.db (SQLite)
Export fürs Dashboard	~/.whoop-mcp/whoop.json

Über WHOOP_MCP_DATA_DIR und WHOOP_MCP_EXPORT_PATH lassen sich Verzeichnis und Exportpfad verlegen.

Aufbau

config.py      Pfade, Scopes, Secret-Speicher (Schlüsselbund mit Datei-Fallback)
auth.py        OAuth-Flow, lokaler Callback-Server, Token-Rotation
client.py      HTTP-Client: Pagination, 401-Refresh, 429-Backoff
normalize.py   Rohantworten zu flachen Datensätzen mit sinnvollen Einheiten
aggregate.py   Tageszusammenführung, Durchschnitte, Trends
store.py       SQLite-Historie, idempotente Upserts
sync.py        Abgleich und JSON-Export
server.py      MCP-Tools

Tests

pip install -e ".[dev]"
pytest

Lizenz und Datenschutz

Private Nutzung. Es werden keine Daten an Dritte übertragen — siehe PRIVACY.md.