Elite MCP

Ein MCP-Server (Model Context Protocol), der einem KI-Agenten direkten, Echtzeit-Lese-/Schreibzugriff auf eine selbst gehostete Elite-Instanz gibt – einen persönlichen Fitness-Tracker für Workouts, Ernährung, Cardio und Körpergewicht.

Wenn Sie ein Agent sind, der dies liest, um zu entscheiden, wie dieser Server verwendet werden soll: Lesen Sie die gesamte Datei, bevor Sie ein Tool aufrufen. Sie behandelt, was jedes Tool tut, was seine Argumente bedeuten, welche Einheiten/Formate erwartet werden und wo die Stolperfallen liegen (hauptsächlich: Schreibvorgänge sind sofort und real, es gibt kein Rückgängigmachen). Die Abschnitte „Hinweise zum Datenmodell“ und „Sicherheitshinweise“ unten sind genauso wichtig wie die Tool-Liste selbst.

Was dies ist und was es nicht ist

Elite (die App) speichert alles in einer eigenen SQLite-Datenbank hinter einer einfachen REST-API – kein lokaler Cache, keine Offline-Warteschlange, eine einzige Quelle der Wahrheit. Dieser MCP-Server ist ein dünner Protokolladapter über diese API: Jeder Tool-Aufruf hier ist eine (oder zwei) HTTP-Anfrage an eine spezifische, bereits laufende Elite-Instanz, auf die Sie ihn zeigen. Er hält keinen eigenen Zustand und macht kein Caching – rufen Sie get_workout_history zweimal hintereinander auf und Sie erhalten zwei frische Lesevorgänge.

Es ist keine allgemeine Fitness-API, es spricht nicht mit anderen Apps und führt keine Lebensmittel-Datenbanksuchen durch (keine OpenFoodFacts/USDA-Suche) – diese Suchlogik lebt clientseitig in der Elite-Web-App selbst und ist nicht über HTTP verfügbar. Wenn Sie ein Lebensmittel protokollieren müssen, das nicht bereits in den Daten dieses Benutzers vorhanden ist, verwenden Sie log_food mit Makros, die Sie bereits kennen oder die der Benutzer Ihnen gibt; es gibt hier kein Tool „Suche nach Lebensmittel nach Name“.

Anforderungen

• Eine laufende Elite-Instanz, für die Sie die URL haben (z. B. http://192.168.1.50:8080 oder wo auch immer sie selbst gehostet wird). Siehe das Elite-Repo, falls Sie eine aufsetzen müssen.

• Node.js 18+.

• Wenn diese Elite-Instanz mit gesetztem API_TOKEN gestartet wurde, benötigen Sie denselben Token.

Einrichtung

git clone https://github.com/natyavidhan/elite-mcp.git
cd elite-mcp
npm install
cp .env.example .env   # then fill in ELITE_BASE_URL (and ELITE_API_TOKEN if the server needs one)

Dies ist ein standardmäßiger stdio-MCP-Server – er soll von der eigenen Konfiguration eines MCP-Clients gestartet werden, nicht eigenständig laufen und offen bleiben. Richten Sie Ihren Agenten/Client auf node /path/to/elite-mcp/index.js mit ELITE_BASE_URL (und optional ELITE_API_TOKEN) als Umgebungsvariablen. Für einen Client, der eine JSON-Konfiguration liest (Claude Desktop, Claude Code und die meisten anderen folgen dieser Form):

{
  "mcpServers": {
    "elite": {
      "command": "node",
      "args": ["/path/to/elite-mcp/index.js"],
      "env": {
        "ELITE_BASE_URL": "http://192.168.1.50:8080",
        "ELITE_API_TOKEN": ""
      }
    }
  }
}

Für eine Agenten-Laufzeit ohne JSON-Konfigurations-MCP-Client (z. B. ein benutzerdefinierter Orchestrator) sind dieselben zwei Umgebungsvariablen plus das Starten von node index.js über stdio der gesamte Vertrag – siehe index.js und src/client.js, beide kurz.

Wenn ELITE_BASE_URL nicht gesetzt ist, protokolliert der Prozess einen Fehler auf stderr und beendet sich sofort, anstatt in einem defekten Zustand zu starten.

Werkzeuge

Insgesamt 20 Werkzeuge: 1 Verbindungsprüfung, 11 schreibgeschützte Analysewerkzeuge, 1 Nachschlagewerkzeug und 7 Schreibwerkzeuge. Jedes Werkzeug gibt sein Ergebnis als JSON-Textblock zurück; ein Fehler (Elite nicht erreichbar, falscher Token, 404, Validierungsfehler) kommt als normales Werkzeugergebnis mit isError: true und einem {"error": "..."}-Body zurück – es stürzt die MCP-Verbindung nicht ab, also prüfen Sie das, anstatt Erfolg anzunehmen.

Verbindung

• check_connection – keine Argumente. Ruft /api/health von Elite auf. Rufen Sie dies zuerst auf, wenn etwas anderes fehlschlägt; es sagt Ihnen, ob der Server überhaupt erreichbar ist und ob sein AI Coach aktiviert ist (für diesen MCP-Server irrelevant, aber ein nützliches Signal, dass Sie mit der richtigen Instanz sprechen).

Analyse (schreibgeschützt)

Diese spiegeln genau das wider, was Elites eigener integrierter AI Coach intern aufruft – gleiche Funktionen, gleiche Mathematik, sodass die Zahlen hier immer mit dem übereinstimmen, was der Benutzer in der App sieht.

• get_workout_history({ days? }) – Sitzungen der letzten N Tage (Standard 30): Datum, Übungen, Sätze, Gesamtvolumen.

• get_exercise_trend({ exerciseName, limit? }) – bestes Gewicht pro Sitzung für eine Übung im Zeitverlauf, plus sein Allzeit-PR. exerciseName wird unscharf abgeglichen (exakte ID, exakter Name oder Teilstring) – Sie benötigen list_exercises nicht zuerst, nur um einen Trend zu lesen.

• get_personal_records({ limit? }) – bestes Gewicht und bestes Einzelsatzvolumen pro Übung, schwerste zuerst.

• get_muscle_volume({ date }) – Muskel-für-Muskel-Volumen für einen bestimmten Tag (primäre Muskeln volle Anrechnung, sekundäre halbe Anrechnung).

• get_weekly_muscle_summary({ days? }) – Gesamtvolumen pro Muskel über die letzten N Tage (Standard 7), sortiert – verwenden Sie dies, um zu finden, was untertrainiert ist.

• get_muscle_exercise_split({ muscle, days? }) – welche Übungen das Volumen eines Muskels ausmachen und welchen Anteil jede hat (z. B. „Wie ist meine Trizeps-Aufteilung“). muscle muss einer der unten aufgeführten Enum-Werte sein.

• get_food_log({ date }) – jeder Eintrag, der an einem Datum protokolliert wurde, mit Makros, plus die Tagesgesamtwerte.

• get_nutrition_trend({ days? }) – tägliche Kalorien-/Makro-Gesamtwerte über die letzten N Tage (Standard 7) plus die konfigurierten Tagesziele des Benutzers.

• get_cardio_summary({ days? }) – Cardio-Sitzungen über die letzten N Tage (Standard 30) plus persönliche Bestleistungen.

• get_body_weight_trend({ days? }) – Einträge über die letzten N Tage (Standard 90) plus aktuell/Start/Veränderung/7-Tage-Durchschnitt.

• get_consistency({ days? }) – pro Tag, ob der Benutzer ein Workout, Essen, Cardio und Körpergewicht protokolliert hat, über die letzten N Tage (Standard 14).

Nachschlagen

• list_exercises({ query? }) – der vollständige Übungskatalog (integriert + benutzerdefinierte Übungen dieser Instanz), optional gefiltert durch einen case-insensitiven Teilstring-Abgleich auf ID oder Name. Rufen Sie dies vor log_workout_set auf, wenn Sie die genaue exerciseId nicht bereits kennen – der Katalog verwendet spezifische IDs wie barbell_bench_press, nicht Freitext, und log_workout_set lehnt alles ab, was keine echte ID ist.

Schreibvorgänge

Jeder Schreibvorgang hier wirkt sofort auf der Live-Elite-Instanz – siehe Sicherheitshinweise unten, bevor Sie diese auf echten Daten einer Person verwenden.

• log_workout_set({ date, exerciseId, reps, weightKg, rpe? }) – protokolliert einen Satz. Erstellt die Workout-Sitzung des Tages automatisch, falls sie noch nicht existiert. Gibt den erstellten Satz und isPR: true/false zurück. rpe (Rate der wahrgenommenen Anstrengung, 1–10) ist optional.

• delete_workout_set({ setId }) – löscht einen protokollierten Satz.

• delete_workout_session({ sessionId }) – löscht eine gesamte Sitzung und jeden Satz darunter. Es gibt keinen Bestätigungsschritt – dieses Werkzeug tut genau das, was es sagt.

• log_food({ date, mealType, name, quantityG, calories, protein?, carbs?, fat? }) – protokolliert einen Lebensmitteleintrag. Makros sind die Gesamtwerte für quantityG, nicht pro 100 g (dieses Werkzeug führt diese Umrechnung für Sie durch). Erstellt im Hintergrund ein Lebensmittel mit manual-Quelle.

• delete_food_log({ logId }) – löscht einen protokollierten Lebensmitteleintrag.

• log_cardio_session({ date, activityType, durationSeconds, distanceKm?, avgHeartRate?, caloriesBurned?, notes? }) – protokolliert eine Cardio-Sitzung.

• log_body_weight({ date, weightKg, bodyFatPct?, notes? }) – Upsert nach Datum: Das erneute Protokollieren für ein Datum, das bereits einen Eintrag hat, überschreibt diesen, anstatt ein Duplikat zu erstellen. Dies ist beabsichtigt (so verhält sich auch die Elite-App selbst), kein Fehler.

Hinweise zum Datenmodell

• Daten sind immer YYYY-MM-DD-Zeichenfolgen, ohne Zeitkomponente, ohne Zeitzone. Es gibt keinen „heute“-Helfer auf diesem Server – wenn ein Benutzer sagt „logge das für heute“, lösen Sie das heutige Datum selbst auf, bevor Sie ein Werkzeug aufrufen.

• IDs (sessionId, setId, logId, exerciseId usw.) sind undurchsichtige Zeichenfolgen, die vom Elite-Server erstellt werden (oder bei Übungen in seinem Katalog definiert sind) – konstruieren oder raten Sie niemals eine. Holen Sie sie aus dem Ergebnis eines vorherigen Werkzeugs (eine log_workout_set-Antwort gibt Ihnen eine echte set.id und sessionId) oder aus list_exercises.

• muscle-Enum (für get_muscle_exercise_split): chest, triceps, shoulder, lats, bicep, forearm, traps, quads, hamstrings, glutes, calves, abs.

• mealType: breakfast, lunch, dinner, snack.

• activityType: run, walk, cycle, swim, other.

• Gewichte sind Kilogramm, Entfernungen sind Kilometer, Dauern sind Sekunden – immer, unabhängig davon, in welchem Einheitensystem die Benutzeroberfläche von Elite eingestellt ist.

Sicherheitshinweise

• Es gibt kein Rückgängigmachen. delete_workout_set, delete_workout_session und delete_food_log sind echte, sofortige Löschungen gegen die tatsächliche Trainings-/Ernährungshistorie des Benutzers. Rufen Sie ein Löschwerkzeug nicht spekulativ auf oder „nur um zu sehen, was passiert“ – bestätigen Sie zuerst mit dem Benutzer, es sei denn, sie haben die Löschung ausdrücklich verlangt.

• log_body_weight überschreibt stillschweigend einen vorhandenen Eintrag für dieses Datum, anstatt einen Fehler zu melden oder zu fragen – wenn Sie nicht sicher sind, ob der Benutzer das heutige Gewicht bereits protokolliert hat, rufen Sie zuerst get_body_weight_trend auf.

• Dieser Server führt keine Autorisierung über den einzelnen gemeinsamen ELITE_API_TOKEN hinaus durch (falls die Zielinstanz einen verwendet) – er hat genau so viel Zugriff, wie dieser Token gewährt, was standardmäßig alles ist. Behandeln Sie ihn entsprechend.

Repository-Struktur

index.js         entry point — starts the stdio MCP server
src/client.js     fetch wrapper around the target Elite instance's REST API
src/tools.js      every tool's schema + implementation

Verwandt

• natyavidhan/elite – der Tracker selbst. Seine README dokumentiert die vollständige REST-API, auf der dieser Server aufbaut (/api/data/*, /api/workout/*, /api/analytics/* usw.), falls Sie etwas benötigen, das dieser MCP-Server nicht bereits als Werkzeug bereitstellt.