Garmin Connect MCP server

Ein MCP-Server für Krafttraining mit Garmin Connect. Plane eine Trainingseinheit im Gespräch mit einem KI-Assistenten, übertrage sie auf deine Uhr und lies zurück, was du tatsächlich gestemmt hast.

Inoffiziell. Nicht mit Garmin verbunden, von Garmin weder unterstützt noch befürwortet. Garmin und Garmin Connect sind Marken von Garmin Ltd. Dieses Projekt spricht über den reverse-engineerten python-garminconnect-Client mit Garmins privaten Workout-Service-Endpunkten, daher kann Garmin die Schnittstelle jederzeit ohne Vorankündigung ändern oder außer Funktion setzen. Nutzung auf eigene Gefahr, und prüfe deine eigenen Verpflichtungen gemäß Garmins Nutzungsbedingungen.

Alles läuft lokal. Deine Zugangsdaten bleiben auf deinem Rechner und gehen ausschließlich an Garmin.

Warum es das gibt

Garmin Connect importiert keine .FIT-Dateien für Workouts – der FIT-Import funktioniert nur für abgeschlossene Aktivitäten, nicht für geplante Workouts. Deine Optionen sind die Connect-Weboberfläche von Hand oder derselbe private Endpunkt, den auch die Web-App aufruft. Dieses Projekt geht den zweiten Weg und legt eine MCP-Schnittstelle darauf, sodass ein Workout aus einem Gespräch entstehen kann, statt aus zwanzig Minuten Klicken.

Werkzeuge

delete_workout ist das einzige destruktive Werkzeug.

Einrichtung

Erfordert Python 3.12 oder neuer (garminconnect 0.3.x benötigt es).

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh erstellt .venv/ im Projektverzeichnis, installiert Abhängigkeiten und kopiert .env.example nach .env. Es wird nichts systemweit installiert. Falls dein neuestes Python für eine Abhängigkeit noch keine Wheels hat, überschreibe die Python-Version:

PYTHON=python3.13 ./setup.sh

Trage deinen Garmin-Login in .env ein und authentifiziere dich dann einmal:

./.venv/bin/python garmin_login.py

Dieser Schritt ist bewusst interaktiv. Garmin kann nach einem MFA-Code fragen, und der MCP-Server hat kein Terminal, auf dem er fragen könnte – er würde einfach hängen. Der Login speichert Tokens in ~/.garminconnect, und der Server verwendet sie von da an stillschweigend weiter. Führe ihn nur erneut aus, wenn der Server meldet, dass die Sitzung abgelaufen ist.

Verifiziere den Build ohne Netzwerkzugriff:

./.venv/bin/python garmin_mcp.py --self-test

Mit einem Client verbinden

Claude Desktop

Füge zu claude_desktop_config.json hinzu – unter macOS unter ~/Library/Application Support/Claude/, unter Windows unter %APPDATA%\Claude\:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

Verwende absolute Pfade und den Interpreter des venv anstelle eines bloßen python – die App erbt nicht das PATH deiner Shell. Starte die App danach neu.

Alles andere

Es ist ein Standard-stdio-MCP-Server, daher funktioniert jeder Client. Zum Debuggen ohne einen Client:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

Programme

Ein Programm ist eine JSON-Datei in programs/, die eine mehrtägige Vorlage beschreibt. sync_program überträgt jedes Workout darin, abgeglichen anhand des Namens – vorhandene Workouts werden an Ort und Stelle aktualisiert, neue werden erstellt. Siehe programs/example.json für eine kommentierte Vorlage.

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

Ein Block ist eine Wiederholungsgruppe, die repeat-mal läuft. Ein Schritt ist entweder eine Übung (exercise + reps, optional weight_kg und note) oder eine Pause (rest_seconds). Ein Superset ist ein Block, der beide Übungen mit einer kurzen Pause dazwischen und einer langen Pause am Ende enthält. Lass weight_kg bei Eigengewichtsübungen weg. Lass warmup für den standardmäßigen Aufwärmschritt weg oder setze es auf "", um keinen zu verwenden.

programs/*.json wird – abgesehen vom Beispiel – von Git ignoriert, sodass dein eigenes Training nie in einem Commit landet.

Fallstricke

Garmin blendet unbekannte Übungsnamen stillschweigend aus. Der Upload liefert 200, und die Übung erscheint mitten in der Einheit namenlos auf der Uhr. Genau deshalb gibt es search_exercises, und deshalb wird jeder Name vor dem Upload mit dem Katalog abgeglichen. Anzeigenamen sind auf eine Art und Weise mit Bindestrichen geschrieben, die niemand tippt – „Rope Press-down“, „Close-grip Chin-up“ –, daher normalisiert die Suche die Zeichensetzung und versteht Kurzformen wie „db“, „bb“, „ohp“, „rdl“, „skullcrusher“.

Die beiden Hälften der API sind sich bei den Gewichtseinheiten uneinig. Der Workout-Service akzeptiert weightValue in Kilogramm, obwohl weightUnit "factor": 1000.0 enthält. Activity-Payloads – das, was du gestemmt hast – melden Gramm. Beides wird berücksichtigt; „korrigiere“ keines davon.

Die Round-Trip-Verifizierung kann einen Einheitenfehler nicht erkennen. Sie vergleicht, was Garmin gespeichert hat, mit dem, was gesendet wurde, und Garmin speichert zuverlässig, was auch immer du sendest. Als Gramm gesendet wurden, bestand der Check und Connect zeigte „75.000 kg“ an. Wirf in Connect einen prüfenden Blick auf deinen ersten Upload.

Aktualisiere, statt zu löschen und neu zu erstellen. Wenn die Workout-ID erhalten bleibt, behandelt die Uhr die Änderung als Bearbeitung. Beim Neuerstellen verwirft sie die alten Workouts und lädt neue herunter – genau daraus entstehen veraltete Duplikate.

429 und 401 sehen gleich aus. Garmin begrenzt Logins pro IP aggressiv. Wenn der erste Login-Transport gedrosselt wird, meldet der Fallback von garminconnect ein irreführendes 401. Wenn du kurz zuvor eine 429 gesehen hast, liegt eine Drosselung vor – warte 30–60 Minuten und versuche es nicht in einer Schleife erneut, das verlängert die Sperre. Um ein wirklich falsches Passwort auszuschließen: garmin_login.py --check-env.

Aufbau

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

Lizenz

MIT – siehe LICENSE.

Basiert auf python-garminconnect (MIT) und dem MCP Python SDK (MIT).