Garmin Read-Only MCP

Eine bewusst eng begrenzte Garmin-Connect-Integration für die lokale Nutzung mit Hermes Agent. Sie synchronisiert ausgewählte Garmin-Zusammenfassungen in einen nur für den Eigentümer zugänglichen SQLite-Cache und stellt anschließend ausschließlich diesen normalisierten Cache über drei schreibgeschützte MCP-Tools bereit.

Dieses Projekt verwendet den von der Community gepflegten python-garminconnect-Client und nicht dokumentierte Garmin-Connect-Endpunkte. Es ist weder mit Garmin verbunden noch von Garmin unterstützt. Endpunkte können sich ändern, und automatisierter Zugriff kann Risiken für das Konto oder die Nutzungsbedingungen mit sich bringen. Das offizielle Garmin-Connect-Entwicklerprogramm bleibt der bevorzugte Weg für genehmigte Geschäftsintegrationen.

Sicherheitsmodell

Das Design trennt den Netzwerkzugriff vom MCP-Prozess:

1. garmin-readonly-auth führt einmalig einen interaktiven Login in einem lokalen Terminal durch. Passwort- und MFA-Eingaben werden verborgen und niemals als Befehlsargumente akzeptiert.

2. garmin-readonly-sync lädt wiederverwendbares lokales Sitzungsmaterial, ruft ein begrenztes Datumsfenster ab, entfernt Upstream-Felder und schreibt normalisierte Zusammenfassungen in SQLite.

3. garmin-readonly-mcp importiert weder den Garmin-Client noch Sitzungsmaterial. Es liest ausschließlich den normalisierten SQLite-Cache und lehnt Caches ab, die Symlinks sind, keine regulären Dateien sind, nicht dem aktuellen Benutzer gehören oder für Gruppen- oder andere Benutzer zugänglich sind.

Das Standard-Zustandsverzeichnis ist:

~/.local/share/garmin-readonly-mcp/
├── tokens/          # Garmin session material, mode 0700/0600
└── cache.sqlite3    # normalized cache, mode 0600

Setzen Sie die nicht geheime Umgebungsvariable GARMIN_READONLY_HOME, um ein anderes Wurzelverzeichnis zu verwenden. Platzieren Sie das Zustandsverzeichnis niemals innerhalb des Repositorys.

Related MCP server: garmin-mcp-local

Datenumfang

Der Cache und das MCP stellen ausschließlich Folgendes bereit:

• Tägliche Gesamtkalorien, aktive Kalorien und BMR-/Ruhekalorien

• Schritte und Ruhepuls, sofern verfügbar

• Aktivitätstyp, Startzeit, Dauer, Distanz und Kalorien

• Schlafdauer/-wert, Body Battery, nächtliche HRV/Status und Trainingsbereitschaft, sofern verfügbar

Sie schließen bewusst aus:

• Garmin-Profil- und Sozialdaten

• Kontokennungen und Aktivitäts-IDs

• Gerätedetails

• GPS-Koordinaten, Routen und FIT/GPX/TCX-Dateien

• Gewicht und Körperzusammensetzung

• Rohe Garmin-Antworten

• Hochlade-, Aktualisierungs-, Planungs- oder Löschvorgänge

• Allgemeiner oder beliebiger Garmin-API-Zugriff

Garmin-Kalorienwerte sind Aktivitätskontext und keine Anweisung, die Nahrungsaufnahme zu erhöhen.

Voraussetzungen

• Linux oder eine andere Unix-ähnliche Umgebung mit privaten Dateiberechtigungen

• Python 3.12+

• uv

• Ein Garmin-Connect-Konto

Installation

git clone https://github.com/alexpomsft/garmin-readonly-mcp.git
cd garmin-readonly-mcp
uv sync --frozen

Lokal authentifizieren

Führen Sie dies in einem privaten lokalen Terminal aus – nicht in Telegram, Chat, Shell-Verlauf oder auf einem geteilten Bildschirm:

uv run garmin-readonly-auth

Der Befehl fragt lokal nach E-Mail, verborgenem Passwort und verborgener MFA, falls Garmin dies verlangt. Er speichert wiederverwendbares Sitzungsmaterial, aber nicht das Passwort.

Synchronisieren

Standardmäßig werden heute und gestern synchronisiert:

uv run garmin-readonly-sync

Ein begrenztes historisches Zeitfenster kann angefordert werden:

uv run garmin-readonly-sync --end-date 2026-08-18 --days 14

--days muss zwischen 1 und 31 liegen. Anbieterfehler werden durch eine feste öffentliche Meldung ersetzt, damit rohe Garmin-Antworten und Authentifizierungsdetails nicht ausgegeben werden.

Den MCP-Server ausführen

Nach mindestens einer erfolgreichen Synchronisierung:

uv run garmin-readonly-mcp

Der stdio-Server stellt genau Folgendes bereit:

• get_daily_activity(date: YYYY-MM-DD)

• get_recent_activities(days: 1..31 = 7)

• get_recovery_summary(date: YYYY-MM-DD)

Tool-Schemas lehnen nicht deklarierte Argumente ab.

Mit Hermes Agent verbinden

Verwenden Sie den MCP-Befehl von Hermes, anstatt config.yaml manuell zu bearbeiten:

hermes mcp add garmin-readonly \
  --command /absolute/path/to/garmin-readonly-mcp/.venv/bin/garmin-readonly-mcp
hermes mcp test garmin-readonly

Starten Sie Hermes nach dem Hinzufügen des Servers neu, damit seine Tools erkannt werden. An die MCP-Konfiguration werden keine Anmeldedaten oder Session-Token-Pfade übergeben; sie verwendet das private Standard-Zustandsverzeichnis. Falls GARMIN_READONLY_HOME angepasst wurde, übergeben Sie ausschließlich diese nicht geheime Einstellung mit hermes mcp add ... --env GARMIN_READONLY_HOME=/private/path.

Entwicklung und Verifizierung

uv sync --frozen
uv run pytest --cov=garmin_readonly_mcp --cov-report=term-missing
uv run ruff check .
uv run mypy src tests
uv run pip-audit

Die Implementierung wurde mit zunächst fehlschlagenden Tests entwickelt. CI führt dieselben Test-, Lint-, Typüberprüfungs- und Abhängigkeits-Audit-Gates aus.

Einschränkungen

• Garmin-Connect-Endpunkte wurden per Reverse Engineering ermitt