garmin-mcp

Ein lokaler MCP-Server, der Ihre Garmin-Connect-Aktivitäts-, Gesundheits- und Trainingsdaten (Aktivitäten, HRV, Schlaf, Herzfrequenz, Stress, Body Battery, Trainingsbereitschaft, HF-/Leistungszonen, Laktatschwelle, FTP, VO2max, persönliche Rekorde, Workouts, geplante Workouts und Trainingspläne) als Werkzeuge in Claude Desktop bereitstellt.

Er kommuniziert direkt mit der Live-Garmin-Connect-API über die garminconnect-Bibliothek. Die Daten sind schreibgeschützt – es wird nie etwas an Garmin zurückgeschrieben.

So funktioniert die Authentifizierung

Der Garmin-Login erfolgt absichtlich an zwei getrennten Stellen:

• scripts/setup_auth.py – ein interaktives Skript, das Sie selbst in einem Terminal ausführen. Es meldet sich mit Ihrer E-Mail/Passwort an, fordert Sie zur Eingabe eines MFA-Codes auf, falls Garmin einen verlangt, und speichert das daraus resultierende Sitzungstoken in ~/.garmin_mcp/tokens.

• Der MCP-Server (src/garmin_mcp/server.py), der von Claude Desktop headless gestartet wird, lädt dieses zwischengespeicherte Token nur und erneuert es stillschweigend. Er fragt nie nach MFA – Claude Desktop bietet ihm kein Terminal für Eingabeaufforderungen, und ein Blockieren auf stdin würde dort Tool-Aufrufe aufhängen. Wenn die zwischengespeicherte Sitzung fehlt oder abgelaufen ist, schlagen Tool-Aufrufe mit einer Fehlermeldung fehl, die Sie auffordert, setup_auth.py erneut auszuführen.

Ihr Garmin-Passwort wird im macOS-Schlüsselbund gespeichert (Eintrag/Dienst garmin-mcp, in Keychain Access einsehbar), nie in eine Datei geschrieben. Nur Ihre Garmin-Login-E-Mail (nicht geheim) wird in ~/.garmin_mcp/config.json gespeichert.

Einrichtung

1. Abhängigkeiten installieren:

   cd garmin_mcp
   uv sync

2. Führen Sie den einmaligen interaktiven Login aus:

   uv run python scripts/setup_auth.py

   Geben Sie Ihre Garmin-Connect-E-Mail und Ihr Passwort ein (das Passwort wird dann für das nächste Mal im Schlüsselbund gespeichert). Geben Sie den MFA-Code ein, wenn Sie dazu aufgefordert werden. Bei Erfolg sehen Sie eine Bestätigung und den Pfad zum Token-Cache.

3. Registrieren Sie den Server bei Claude Desktop, indem Sie ~/Library/Application Support/Claude/claude_desktop_config.json bearbeiten und (neben allen anderen mcpServers-Einträgen) Folgendes hinzufügen:

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. Beenden Sie Claude Desktop vollständig (Cmd+Q, nicht nur das Fenster schließen) und öffnen Sie es erneut. Das Werkzeuge/Hammer-Symbol sollte die garmin-Werkzeuge auflisten.

Werkzeuge

Alle Datumsparameter akzeptieren YYYY-MM-DD und sind standardmäßig auf heute gesetzt.

Fehlerbehebung

Ein Tool-Aufruf gibt eine Meldung „Garmin-Sitzungsfehler“ / „run setup_auth.py“ zurück. Ihr zwischengespeichertes Aktualisierungstoken ist abgelaufen oder wurde widerrufen (das passiert gelegentlich, z. B. nach einer Passwortänderung oder längerer Inaktivität). Führen Sie erneut aus:

uv run python scripts/setup_auth.py

Ratenlimit erreicht. Garmin Connect begrenzt gelegentlich schnelle Anfragen; die zugrunde liegende Bibliothek wiederholt vorübergehende Fehler automatisch, aber wenn Sie einen Ratenlimit-Fehler sehen, warten Sie einen Moment und versuchen Sie es erneut.

Den Server direkt außerhalb von Claude Desktop überprüfen:

uv run mcp dev src/garmin_mcp/server.py

öffnet den MCP Inspector, sodass Sie jedes Werkzeug manuell aufrufen und dessen Ausgabe/Schema prüfen können.

Projektstruktur

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login