hevy-mcp

Verbinde Claude mit deinem Hevy Trainingstagebuch.

hevy-mcp ist ein Model Context Protocol-Server, mit dem Claude (Desktop oder claude.ai) deine Workouts lesen, neue Routinen entwerfen, sie in deiner Hevy-Bibliothek speichern und deine Trainingstrends analysieren kann – dieselbe Art von Zugriff, die ChatGPT-Nutzer durch die offizielle Hevy-Integration erhalten.

You: "Build me a 4-day upper/lower hypertrophy split focused on the muscle groups
      I've trained least over the last 30 days, and save it in a folder called
      'Hypertrophy Block 1'."

Claude: ✓ checked your last 30 days of training (lats and rear delts are behind)
        ✓ created folder "Hypertrophy Block 1"
        ✓ resolved 22 exercises against Hevy's library
        ✓ saved 4 routines: Upper A, Lower A, Upper B, Lower B
        Open the Hevy app to start any of them.

Was du Claude fragen kannst

• Rückblick — "Zeig mir meine letzten 10 Workouts und sag mir, welche Muskelgruppen ich vernachlässigt habe."

• Vorausplanung — "Was ist basierend auf meiner Bankdrück-Historie ein guter Top-Satz für morgen?"

• Routinen erstellen — "Erstelle mir einen 4-Tage-Oberkörper/Unterkörper-Hypertrophie-Split und speichere ihn."

• Routinen bearbeiten — "Tausche am 'Push-Tag A' das Kurzhantel-Schulterdrücken gegen Langhantel-Schulterdrücken, 4 Sätze à 5 Wiederholungen."

• Analysieren — "Schätze mein 1RM bei den Hauptübungen und erstelle ein Diagramm zum Fortschritt beim Kniebeugen über die letzten 90 Tage."

Voraussetzungen

• Ein Hevy PRO-Abonnement (die Entwickler-API erfordert dies).

• Dein Hevy-API-Schlüssel – erhältlich unter https://hevy.com/settings?developer.

• Entweder Python 3.11+ oder Docker.

• Claude Desktop oder ein claude.ai-Arbeitsbereich, der benutzerdefinierte Connectors unterstützt.

Schnellstart — Claude Desktop (5 Minuten)

1. Installation

# Easiest, with uv (https://docs.astral.sh/uv/):
uv tool install hevy-mcp

# Or with pipx:
pipx install hevy-mcp

# Or with plain pip:
python -m pip install hevy-mcp

2. Zu Claude Desktop hinzufügen

Öffne die Konfigurationsdatei von Claude Desktop:

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

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

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

Füge den hevy-Eintrag unter mcpServers hinzu (erstelle die Datei, falls sie nicht existiert):

{
  "mcpServers": {
    "hevy": {
      "command": "hevy-mcp",
      "env": {
        "HEVY_API_KEY": "sk_live_paste_your_key_here"
      }
    }
  }
}

Falls hevy-mcp nicht in deinem PATH liegt (uv-tool-Installationen werden manchmal vom Claude Desktop-Launcher nicht erkannt), verwende den absoluten Pfad, den du über which hevy-mcp erhältst – zum Beispiel /Users/you/.local/bin/hevy-mcp.

3. Claude Desktop neu starten

Beende das Programm vollständig (⌘Q unter macOS) und öffne es erneut. Du solltest eine Tool-Anzeige sehen, die bestätigt, dass der hevy-Server verbunden ist.

4. Ausprobieren

"Verwende das hevy-Tool, um meine letzten 3 Workouts abzurufen und zusammenzufassen."

Wenn Claude deine echten Workouts anzeigt, bist du fertig. 🎉

Alternative — claude.ai (Remote-Connector)

Wenn du claude.ai im Browser anstelle von Claude Desktop verwendest, führe hevy-mcp als HTTP-Dienst aus und füge ihn als benutzerdefinierten Connector hinzu.

1. Den Server an einem Ort mit HTTPS ausführen

Der einfachste Weg ist Docker auf Fly.io / Render / Railway:

docker build -t hevy-mcp .
docker run --rm -p 8000:8000 -e HEVY_API_KEY=sk_live_... hevy-mcp

Oder direkt über die CLI:

hevy-mcp --http --host 0.0.0.0 --port 8000

Der MCP-Endpunkt befindet sich unter /mcp.

2. Als benutzerdefinierten Connector hinzufügen

Gehe in claude.ai zu Settings → Connectors → Add custom connector und verwende deine öffentliche HTTPS-URL, die auf /mcp endet (z. B. https://hevy-mcp.fly.dev/mcp).

Hinweis für mehrere Benutzer

Wenn mehrere Benutzer dieselbe Bereitstellung nutzen, binde HEVY_API_KEY nicht in die Container-Umgebung ein – sende ihn stattdessen als Header pro Anfrage. Der Server liest X-Hevy-Api-Key, falls vorhanden, und greift andernfalls auf die Umgebungsvariable zurück. Ein kleiner Reverse-Proxy zur Authentifizierungsinjektion (Cloudflare Worker, Nginx) vor dem Server ist das übliche Muster.

Was es kann (vollständige Tool-Liste)

Unter der Haube:

• Intelligentes Caching — die Übungsbibliothek wird einmal abgerufen und für 24 Stunden zwischengespeichert; die Fuzzy-Suche läuft im Arbeitsspeicher.

• Ratenbegrenzungs-bewusst — drosselt bei 429-Fehlern und respektiert Retry-After.

• Idempotente Schreibvorgänge — beim Erstellen einer Routine mit einem doppelten Titel im selben Ordner wird Claude aufgefordert, dies vor der Duplizierung zu bestätigen.

• LLM-freundliche Fehler — jeder Fehler wird als { error, hint } zurückgegeben. Der Hinweis schlägt den nächsten konkreten Tool-Aufruf vor.

• Protokolliert niemals deinen API-Schlüssel.

Fehlerbehebung

Häufigste Ursache: Der command in claude_desktop_config.json befindet sich nicht im PATH des Launchers. Ersetze "command": "hevy-mcp" durch den absoluten Pfad von which hevy-mcp (oder where hevy-mcp unter Windows). Starte Claude Desktop neu.

• Überprüfe, ob du den Schlüssel in den env-Block (nicht in den args-Block) eingefügt hast.

• Bestätige, dass dein Hevy PRO-Abonnement aktiv ist.

• Erneuere deinen Schlüssel unter https://hevy.com/settings?developer und versuche es erneut.

search_exercise_templates ist fuzzy, aber nicht magisch. Wenn Claude die falsche Übung auswählt, bitte es darum, "erneut mit einem spezifischeren Namen zu suchen" oder einen equipment-Filter (z. B. "barbell") zu übergeben.

Die Übungsbibliothek wird beim ersten Nachschlagen abgerufen (einmalig, ~200ms). Jeder weitere Aufruf greift auf den Cache im Arbeitsspeicher zu. Der Cache hält 24 Stunden.

Entwicklung

git clone https://github.com/Vellarasan/hevy-mcp.git
cd hevy-mcp
uv sync --extra dev          # creates .venv and installs deps
pytest -q                    # offline tests (no real API needed)

# Run against your real Hevy account:
HEVY_API_KEY=sk_live_... python smoke_test.py

# Stdio (Claude Desktop):
hevy-mcp

# HTTP (claude.ai):
hevy-mcp --http --port 8000

Siehe CONTRIBUTING.md für die ausführlichere Version.

Projektlayout

hevy-mcp/
├── src/hevy_mcp/
│   ├── server.py        # transport bootstrap (stdio + streamable-http)
│   ├── hevy_client.py   # async httpx client w/ retries & error mapping
│   ├── schemas.py       # Pydantic models
│   ├── cache.py         # 24-hour TTL cache
│   ├── errors.py        # HevyApiError + tool_guard
│   ├── formatters.py    # JSON → readable text
│   └── tools/           # workouts, routines, folders, templates, webhooks, analytics
├── tests/
└── Dockerfile

Releases

Siehe CHANGELOG.md. Getaggte Releases werden automatisch auf PyPI veröffentlicht.

Lizenz

MIT.

Dank

Das Design dieses Projekts verdankt Ideen zwei früheren Community-Implementierungen: chrisdoc/hevy-mcp (TypeScript) und SrdjanCodes/hevy-mcp (Python). Kein Fork – aber einen Blick wert, wenn du eine andere Sprache oder Funktionsmischung bevorzugst.

hevy-mcp ist ein Community-Projekt und ist nicht mit Hevy verbunden oder von Hevy unterstützt.