garmin-mcp

Ein kleiner MCP-Server, der Claude Desktop schreibgeschützten Zugriff auf Lauf-, Krafttrainings- und Kalorien-Daten von Garmin Connect bietet. Es gibt drei Werkzeuge und die Einrichtung dauert etwa fünfzehn Minuten.

Ich habe dies gebaut, weil ich unter anderem meinen Fortschritt verfolgen und einige Daten aus meinem eigenen Training analysieren wollte (z. B. wie hat sich mein Tempo bei lockeren Läufen verändert, oder was habe ich an Tagen gehoben, an denen ich auch gelaufen bin), ohne CSVs von Hand exportieren zu müssen. Es kommuniziert direkt mit der Connect-API von Garmin, sodass kein Drittanbieter-Dienst dazwischengeschaltet ist und nichts hochgeladen wird.

Die Werkzeuge

• list_runs(limit, start): Datum, Laufart, Distanz, Zeit, durchschnittliches Tempo, durchschnittliche und maximale Herzfrequenz, Kadenz, Temperatur. Deckt auch Laufbandläufe ab.

• list_strength(limit, start): Datum, Name der Einheit, Dauer, Sätze, Wiederholungen, Brutto- und aktive Kalorien, durchschnittliche und maximale Herzfrequenz.

• daily_calories(days, end): Tagesgesamtwerte, aktive Kalorien und BMR-Kalorien, plus Schritte und Ruheherzfrequenz.

start ist ein Zeilenoffset und end ist ein Datum, sodass Claude durch Jahre der Geschichte blättern kann, anstatt nur die letzten Einträge zu sehen.

Alles ist schreibgeschützt. Die darunterliegende Bibliothek (garth-ng) stellt zwar Schreib-Endpunkte bereit, aber nichts hier ruft sie auf: Das ist das Einzige, was dies sicher macht, da die Token selbst vollen Kontozugriff gewähren.

Voraussetzungen

Python 3.12+, uv, Claude Desktop und ein Garmin Connect-Konto. Die folgenden Befehle setzen eine Unix-Shell voraus, also macOS oder Linux; Windows funktioniert auch, aber die Pfade unterscheiden sich. Claude Desktop läuft auf macOS, Windows und Linux (Beta, auf Ubuntu und Debian). Dies wird nicht in der Claude Mobile App oder in claude.ai funktionieren, da ein lokaler stdio-Server keine URL für diese bereitstellt.

Einrichtung

1. Ändern Sie Ihr Garmin-Passwort zu etwas, das Sie nirgendwo anders verwenden, da Sie es gleich in ein Skript eingeben werden.

2. Klonen und installieren:

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. Einmal authentifizieren. Dies tauscht Ihr Passwort gegen OAuth-Token, die in ~/.garth gespeichert werden, danach wird das Passwort nie wieder benötigt:

cd garmin-mcp-public
uv run auth_setup.py

Geben Sie Ihren MFA-Code ein, wenn Sie dazu aufgefordert werden. Das OAuth1-Token hält etwa ein Jahr und das OAuth2-Token aktualisiert sich selbst, also ist dies ungefähr eine jährliche Aufgabe. Behandeln Sie ~/.garth als Anmeldeinformation: Jeder, der es besitzt, kann Ihr gesamtes Garmin-Konto lesen.

4. Testen Sie die Werkzeuge direkt, bevor Sie Claude einbeziehen. Ein Fehler hier ist ein Authentifizierungs- oder Endpunktproblem und kein MCP-Problem, und es ist viel schneller, auf dieser Ebene zu debuggen als über die Desktop-Protokolle:

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. Finden Sie die beiden absoluten Pfade, die die Konfiguration benötigt:

cd garmin-mcp-public
which uv
pwd

6. Erstellen oder bearbeiten Sie die Konfigurationsdatei von Claude Desktop und fügen Sie den folgenden Block ein, wobei Sie die beiden Pfade durch die Ausgabe von Schritt 5 ersetzen. Durch das Einfügen Ihrer tatsächlichen Pfade werden auch beide Instanzen von YOUR_USERNAME entfernt. Die Datei befindet sich unter ~/Library/Application Support/Claude/claude_desktop_config.json auf macOS und %APPDATA%\Claude\claude_desktop_config.json auf Windows; unter der Linux-Beta finden Sie die aktuelle Position in der Claude Desktop-Dokumentation von Anthropic.

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

Beide Pfade müssen absolut sein. Desktop startet den Server mit einem minimalen PATH, sodass ein bloßes uv fehlschlägt, obwohl es in Ihrer Shell funktioniert. Wenn Sie bereits andere Server konfiguriert haben, fügen Sie den garmin-Eintrag neben ihnen hinzu, anstatt das Objekt zu ersetzen. Wenn Sie diese Datei in TextEdit bearbeiten, schalten Sie zuerst die intelligenten Anführungszeichen aus: geschweifte Anführungszeichen sind ungültiges JSON.

7. Beenden Sie Claude Desktop vollständig (Cmd-Q, nicht nur das Fenster schließen) und öffnen Sie es erneut. Die Konfiguration wird nur beim Start gelesen. Fragen Sie dann etwas wie „Zeig mir meine letzten fünf Läufe und meinen Kalorienverbrauch diese Woche“ und bestätigen Sie die Tool-Aufrufe.

Falls es nicht funktioniert

Validieren Sie zuerst das JSON, dann lesen Sie den stderr des Servers. Diese Pfade sind die macOS-Pfade; passen Sie sie für Ihre Plattform an:

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

Fehler bei jedem Aufruf bedeuten in der Regel, dass die Token abgelaufen sind: führen Sie auth_setup.py erneut aus. Der Dialog „Benutzerdefinierten Connector hinzufügen“ in Claude ist hier nicht relevant, da er eine entfernte HTTPS-URL erwartet.

Hinweise für Erweiterungen

Die Connect-API von Garmin ist undokumentiert und ihre Feldnamen ändern sich, daher sollten Sie, wenn etwas leer zurückkommt, ein reales Objekt untersuchen, anstatt zu raten. Speichern Sie dies als probe.py im Repository und führen Sie es mit uv run probe.py aus, anstatt es in eine Shell einzufügen:

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

Zwei Verhaltensweisen, die Sie kennen sollten, bevor Sie ein Werkzeug hinzufügen. Der activityType-Filter akzeptiert nur übergeordnete Kategorien: running funktioniert und schließt stillschweigend treadmill_running ein, während strength_training HTTP 400 zurückgibt und als fitness_equipment angefordert und dann in Python gefiltert werden muss. Und jede Aktivität hat etwa hundert Felder, daher sollten Sie sie auf die wenigen reduzieren, die Sie benötigen: Das Zurückgeben von rohem Garmin-JSON überflutet den Kontextfenster bei jedem Aufruf.

Halten Sie die Anzahl der Werkzeuge aus demselben Grund klein. Drei fokussierte Werkzeuge mit beschreibenden Docstrings funktionieren besser als ein Dutzend vage, weil die Docstrings das sind, was Claude liest, wenn es entscheidet, welches Werkzeug aufgerufen werden soll.

MIT-lizenziert.