Personal Garmin MCP

Ein lokaler MCP-Server zum Erstellen und Planen strukturierter Workouts in Garmin Connect über inoffizielle Garmin-Endpunkte.

Dies ist ein experimentelles persönliches Projekt. Garmin kann die Endpunkte ändern, Anfragen drosseln oder eine Sitzung ohne Vorankündigung widerrufen. Setzen Sie den Server nicht ohne separate Authentifizierung dem Internet aus.

Funktionen

• überprüft eine gespeicherte Garmin-Sitzung;

• zeigt Garmin-JSON zur Vorschau an, ohne Änderungen vorzunehmen;

• erstellt Workouts und fügt sie optional dem Kalender hinzu;

• listet die Workout-Bibliothek und den Kalender auf;

• liest abgeschlossene Aktivitäten, kompakte Zusammenfassungen und Runden-/Split-Metriken;

• liest verfügbare Schlaf-, HRV-, Body-Battery-, Trainingsbereitschafts- und Trainingsstatusdaten;

• löscht Workouts und entfernt Workouts aus dem Kalender;

• unterstützt Laufen, Radfahren, Gehen und Wandern;

• unterstützt Zeit-, Distanz- und lap button-Schritte;

• unterstützt Intervall-Wiederholungen;

• unterstützt Tempo-, Herzfrequenz-, Leistungs- und Kadenzziele;

• erfordert confirm=true für jede Änderung.

Related MCP server: garmin-mcp

Installation

Docker Compose — empfohlen

Für die lokale Nutzung ist Docker mit Compose-Unterstützung erforderlich. Erstellen Sie das Image aus dem Repository-Stammverzeichnis:

docker compose build

Der Build installiert Python-Abhängigkeiten mit uv ausschließlich aus uv.lock.

Führen Sie den interaktiven Login einmalig aus. Das Passwort und der MFA-Code werden direkt im Container eingegeben und nicht gespeichert. OAuth-Tokens werden im privaten benannten Volume garmin-mcp_garmin_tokens gespeichert:

docker compose --profile login run --rm garmin-login

Starten Sie den MCP-Server:

docker compose up -d garmin-mcp
docker compose ps

Der Endpunkt ist unter http://127.0.0.1:8000/mcp verfügbar. Um einen anderen lokalen Port zu verwenden:

GARMIN_MCP_PORT=8765 docker compose up -d garmin-mcp

Logs anzeigen oder den Server stoppen:

docker compose logs -f garmin-mcp
docker compose down

docker compose down erhält die Garmin-Tokens. Die Ausführung von docker compose down -v löscht das Volume und seine Tokens.

Lokale Installation ohne Docker

Python 3.12+ und uv sind erforderlich.

cd /path/to/garmin-mcp
uv sync --extra dev

Einmaliger Login

uv run garmin-mcp-login

Das Skript fragt interaktiv nach E-Mail-Adresse, Passwort und MFA-Code, sofern erforderlich. Das Passwort wird nicht gespeichert. OAuth-Tokens werden unter .garmin-tokens/garmin_tokens.json mit eingeschränkten Berechtigungen gespeichert. Das Verzeichnis ist bereits in .gitignore enthalten.

Um Tokens an einem anderen Ort zu speichern:

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp-login

Lokaler MCP über stdio

export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

Beispielkonfiguration für einen MCP-Client:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/garmin-mcp",
      "env": {
        "GARMIN_TOKEN_DIR": "/safe/private/path/garmin-tokens"
      }
    }
  }
}

Streamable HTTP für ChatGPT

export GARMIN_MCP_TRANSPORT=streamable-http
export GARMIN_MCP_HOST=127.0.0.1
export GARMIN_MCP_PORT=8000
export GARMIN_TOKEN_DIR=/safe/private/path/garmin-tokens
uv run garmin-mcp

Endpunkt: http://127.0.0.1:8000/mcp.

ChatGPT muss den Endpunkt über HTTPS erreichen können. Für persönliche Tests kann ein geschützter Tunnel verwendet werden. Setzen Sie diesen MVP nicht direkt dem Internet aus: Er enthält bewusst keinen separaten OAuth-Ressourcenserver für den Zugriff auf den MCP-Server selbst.

Beispielargument für preview_workout

{
  "workout": {
    "name": "6 x 800",
    "sport": "running",
    "description": "Controlled intervals",
    "blocks": [
      {
        "steps": [
          {
            "step_type": "warmup",
            "duration_type": "time",
            "duration_value": 900
          }
        ]
      },
      {
        "repeat": 6,
        "steps": [
          {
            "step_type": "interval",
            "duration_type": "distance",
            "duration_value": 800,
            "target_type": "pace_seconds_per_km",
            "target_low": 250,
            "target_high": 260
          },
          {
            "step_type": "recovery",
            "duration_type": "time",
            "duration_value": 120
          }
        ]
      },
      {
        "steps": [
          {
            "step_type": "cooldown",
            "duration_type": "time",
            "duration_value": 600
          }
        ]
      }
    ]
  }
}

Tempo-Werte werden in Sekunden pro Kilometer angegeben: 250 = 4:10/km und 260 = 4:20/km. Der Server konvertiert sie in die von Garmin Connect verwendeten m/s-Werte.

Nach der Vorschau rufen Sie create_workout mit demselben Objekt, einem Datum im Format YYYY-MM-DD und confirm=true auf.

Schreibgeschützter Trainingskontext

Der Server stellt kompakte schreibgeschützte Tools zur Verfügung, um zukünftige Pläne an abgeschlossene Arbeiten anzupassen:

• list_activities listet Aktivitäten in einem inklusiven Datumsbereich auf, mit optionalem Garmin-Aktivitätstypfilter;

• get_activity_summary gibt Planungsmetriken für eine Aktivität zurück;

• get_activity_splits gibt kompakte Runden- und Intervallmetriken zurück;

• get_recovery_status aggregiert verfügbare Schlaf-, HRV-, Body-Battery-, Trainingsbereitschafts- und Trainingsstatusdaten für ein Datum.

Aktivitätsantworten lassen GPS-Koordinaten und Besitzerdetails absichtlich aus. Erholungsmetriken variieren je nach Garmin-Gerät, Konto und Datum. Eine fehlende Quelle wird als nicht verfügbar zurückgegeben und führt nicht dazu, dass die gesamte Erholungsanfrage fehlschlägt.

Prüfungen

uv run --extra dev pytest
uv run --extra dev ruff check .

Unit-Tests kontaktieren Garmin nicht und erfordern keine Anmeldeinformationen.

Wichtige Einschränkungen

• Dies ist keine offizielle Garmin-Training-API.

• Häufige Logins können HTTP-429-Antworten erhalten; verwenden Sie gespeicherte Tokens erneut.

• Tokens bieten Zugriff auf Garmin Connect und müssen wie ein Passwort geschützt werden.

• Wenn die Erstellung erfolgreich ist, die Planung jedoch fehlschlägt, gibt das Tool created_not_scheduled und workout_id zurück; das erstellte Workout bleibt in der Bibliothek.

• Testen Sie vor der regelmäßigen Nutzung ein einfaches Workout in Garmin Connect und auf dem jeweiligen Uhrenmodell.