hevy-mcp-server

MCP-Server für die Hevy Workout-Tracking-API. Gibt einem LLM Lese- und Schreibzugriff auf Workouts, Routinen, Übungsvorlagen, Übungsverlauf und Körpermaße.

Deckt alle 15 Endpunkte der öffentlichen Hevy-API (v0.0.1) über 27 Tools ab.

Anforderungen

• Node.js 18+

• Ein Hevy Pro-Abonnement – API-Zugriff ist nur mit Pro möglich

• Ein API-Schlüssel von https://hevy.com/settings?developer

Related MCP server: hevy-mcp-server

Installation

pnpm install
pnpm run build

Konfiguration

Setze HEVY_API_KEY in deiner MCP-Client-Konfiguration. Für Claude Desktop in claude_desktop_config.json:

{
  "mcpServers": {
    "hevy": {
      "command": "node",
      "args": ["/absolute/path/to/hevy-mcp-server/dist/index.js"],
      "env": { "HEVY_API_KEY": "your-key-here" }
    }
  }
}

Remote-/HTTP-Modus, lokal:

TRANSPORT=http PORT=3000 pnpm start   # POST JSON-RPC to http://127.0.0.1:3000/mcp

Die Tools interaktiv inspizieren:

HEVY_API_KEY=your-key pnpm run inspect

Bereitstellung (für Claude mobile / claude.ai-Connectors)

Claude verbindet sich mit benutzerdefinierten Connectors aus der Cloud von Anthropic, nicht von deinem Gerät. Daher müssen mobile und claude.ai diesen Server über öffentliches HTTPS erreichen können. Claude Code und Claude Desktop benötigen das nicht – verwende dort stattdessen stdio.

1. Pfad-Geheimnis generieren

openssl rand -hex 32

Der Server weigert sich, ohne gesetztes MCP_PATH_SECRET auf einer Nicht-Loopback-Schnittstelle zu starten, weil ein öffentlicher Endpunkt mit deinem Hevy-Schlüssel ein offener Proxy für dein Konto wäre. Mit gesetztem Geheimnis verschiebt sich der Endpunkt zu /mcp/<secret>, und jeder andere Pfad gibt 404 zurück – auch bei falschem Geheimnis, sodass das Abtasten des Hosts nicht verrät, dass dort ein MCP-Server läuft.

2. Bereitstellen

Das enthaltene Dockerfile und railway.json funktionieren unverändert auf Railway, Render oder Fly. Das Image setzt TRANSPORT=http und HOST=0.0.0.0 und läuft als Nicht-Root-Benutzer. Setze zwei Variablen im Dashboard der Plattform:

PORT wird von der Plattform injiziert. /healthz ist ein nicht authentifizierter Liveness-Healthcheck.

3. Verifizieren

curl -s https://your-app.up.railway.app/healthz
# {"status":"ok","server":"hevy-mcp-server","version":"1.0.0"}

4. Connector hinzufügen

Auf claude.ai in einem Browser – Connectors können nicht aus der mobilen App hinzugefügt werden:

1. Customize → Connectors → Add custom connector

2. URL: https://your-app.up.railway.app/mcp/<secret>

3. Öffne auf deinem Telefon einen Chat und aktiviere ihn unter + → Connectors

Behandle diese URL wie ein Passwort: Sie ist das Einzige, was zwischen dem Internet und deinem Trainingstagebuch steht. Wenn sie durchsickert, rotiere MCP_PATH_SECRET und füge den Connector erneut hinzu.

Tools

Workouts – hevy_list_workouts, hevy_get_workout, hevy_count_workouts, hevy_list_workout_events, hevy_create_workout, hevy_update_workout

Sitzungen – hevy_start_session, hevy_get_active_session, hevy_finish_session, hevy_cancel_session

Routinen – hevy_list_routines, hevy_get_routine, hevy_create_routine, hevy_update_routine

Routinen-Ordner – hevy_list_routine_folders, hevy_get_routine_folder, hevy_create_routine_folder

Übungsvorlagen – hevy_search_exercise_templates, hevy_list_exercise_templates, hevy_get_exercise_template, hevy_create_exercise_template

Fortschritt – hevy_get_exercise_history, hevy_list_body_measurements, hevy_get_body_measurement, hevy_create_body_measurement, hevy_update_body_measurement

Konto – hevy_get_user_info

Jedes Lesetool akzeptiert response_format: "markdown" | "json". Markdown ist die Standardeinstellung und für das Lesen durch ein LLM optimiert; JSON ist die vollständige strukturierte Nutzlast. structuredContent ist unabhängig vom Format immer gefüllt.

Beispiele

„Was habe ich diese Woche trainiert?" → hevy_list_workouts mit page_size=5. Liefert Titel, Dauer, Übungsliste und Gesamtvolumen pro Einheit.

„Logge heute Bankdrücken: 3x8 bei 60 kg" → hevy_search_exercise_templates mit query="bench press", um die ID zu erhalten, dann hevy_create_workout mit drei Sätzen von { weight_kg: 60, reps: 8 }.

„Ich starte jetzt Beine" → hevy_start_session mit title="Leg Day". Die Startzeit wird serverseitig gestempelt, und die Sitzung erscheint in Hevy als laufend. Wenn du fertig bist, schließt hevy_finish_session mit dem, was du ausgeführt hast, die Sitzung mit der tatsächlichen Dauer ab.

„Werde ich bei Kniebeugen stärker?" → hevy_search_exercise_templates mit query="squat", dann hevy_get_exercise_history mit einem start_date. Liefert jeden geloggten Satz neueste zuerst, plus den besten Satz nach geschätztem 1RM.

Designhinweise

Erst suchen, dann schreiben. Hevy hat keine serverseitige Übungssuche, aber jeder Schreibvorgang benötigt eine exercise_template_id. hevy_search_exercise_templates blättert durch den Katalog (bis zu 30 Seiten à 100) und filtert lokal nach Titel, Muskelgruppe, Ausrüstung und nur benutzerdefiniert. Weisen Sie das Modell zuerst auf dieses Tool hin – IDs können nicht erraten werden.

Updates sind Ersetzungen, keine Patches. hevy_update_workout, hevy_update_routine und hevy_update_body_measurement überschreiben die gesamte Ressource; alles Weggelassene wird gelöscht oder auf null gesetzt. Alle drei tragen destructiveHint: true, und ihre Beschreibungen sagen dem Modell, zuerst den aktuellen Zustand zu lesen. Dies sind die einzigen drei destruktiven Tools – die Hevy-API hat keine Lösch-Endpunkte.

Live-Sitzungen sind eine Titelkonvention, kein Serverzustand. Die Hevy-API hat keinen Start-Workout-Endpunkt und kann den In-App-Timer nicht steuern. Daher erstellt hevy_start_session ein echtes Workout im Voraus mit dem Titel 🔴 In Progress — <title>, und hevy_finish_session schreibt es mit der tatsächlichen Endzeit neu. Diese Markierung ist der einzige dauerhafte Anker – der Server hält keinen Zustand zwischen Anfragen, sodass jeder Chat auf jedem Gerät die offene Sitzung findet, indem er die letzten Workouts durchsucht. Der Preis ist, dass eine unfertige Sitzung im Log sichtbar bleibt, und da Hevy kein Löschen anbietet, kann hevy_cancel_session sie nur umbenennen, nie entfernen.

Alles in Kilogramm. Die API hat kein Einheitenfeld. Eingabefelder heißen weight_kg, damit keine Unklarheit darüber besteht, was das Modell sendet, und die Markdown-Ausgabe zeigt beides (60 kg (132.3 lb)), sodass ein US-amerikanischer Leser nicht im Kopf umrechnen muss.

Seitengrößen-Obergrenzen werden clientseitig durchgesetzt. Hevy gibt für eine zu große Seite nur ein nacktes 400 zurück. Die Zod-Schemas begrenzen jeden Endpunkt auf sein dokumentiertes Limit (10 für die meisten, 100 für Übungsvorlagen), sodass das Modell eine präzise Meldung erhält statt einer fehlgeschlagenen Anfrage.

Fehler führen zu nächsten Aktionen. Ein 404 nennt das Tool, das gültige IDs für diese Ressource erzeugt. Ein 409 bei einer Körpermaßnahme verweist auf das Update-Tool. Ein 403 erklärt, dass API-Zugriff Pro erfordert.

Permissive Ausgabeschemas. Die Hevy-Dokumentation warnt, dass diese 0.0.1-API die Struktur ohne Vorankündigung ändern kann. Ausgabeschemas verwenden passthrough() mit optionalen Feldern, sodass eine hinzugefügte Feldänderung nicht zu einem harten Tool-Fehler wird.

Projektstruktur

src/
├── index.ts               # entry point, transport selection
├── constants.ts           # API limits, enums, character limit
├── types.ts               # interfaces for every Hevy entity
├── services/
│   └── hevy-client.ts     # fetch wrapper, auth, error → guidance mapping
├── schemas/
│   ├── inputs.ts          # Zod input schemas
│   └── outputs.ts         # structuredContent schemas
├── formatters/
│   ├── response.ts        # pagination, truncation, format dispatch
│   └── entities.ts        # per-entity markdown rendering
└── tools/
    ├── workouts.ts
    ├── sessions.ts         # in-progress workout tracking
    ├── routines.ts
    ├── exercise-templates.ts
    └── progress.ts

Einschränkungen

• Die Hevy-API ist offiziell Version 0.0.1, und ihre eigene Dokumentation warnt, dass die Struktur sich ändern oder aufgegeben werden kann.

• Der Ordner einer Routine kann nach der Erstellung nicht mehr geändert werden – der Update-Endpunkt akzeptiert kein folder_id.

• Die Ausrüstungsfilterung in der Suche gleicht gegen den Übungstitel ab, da die API Ausrüstung nicht als Feld auf Vorlagen bereitstellt.

• hevy_create_exercise_template gibt eine numerische ID zurück, anders als die String-IDs, die überall sonst in der API verwendet werden.

Tests

pnpm run build
pnpm test         # 45 checks: MCP handshake, tools, sessions, formatting, errors (mocked API)
pnpm run test:http  # 13 checks: path-secret gating, health check, origin allowlist

Beide Suiten laufen gegen einen lokalen Mock, sodass kein API-Schlüssel oder Netzwerkzugriff erforderlich ist.