📡 Configuration Garmin

Cette page détaille l'accès à Garmin Connect utilisé par ai-running-coach.

Architecture

Mode direct (défaut)

flowchart LR
    A["Votre IDE<br/>(agent IA)"] --> B["garmin-mcp<br/>(serveur, liste blanche)"]
    B --> C["Garmin Connect<br/>(API)"]

Mode passerelle (optionnel — power user)

flowchart LR
    A["Votre IDE<br/>(agent IA)"] --> B["leanproxy-mcp<br/>(passerelle)"]
    B --> C["garmin-mcp<br/>(serveur)"]
    C --> D["Garmin Connect<br/>(API)"]

• garmin-mcp — serveur MCP qui expose les données Garmin Connect (activités, santé, sommeil, calendrier, planification d'entraînements). Mode direct par défaut : il est enregistré directement dans votre IDE avec une liste blanche d'outils (GARMIN_ENABLED_TOOLS) pour réduire la taxe de contexte (~151 outils → ~25).
• leanproxy-mcp — passerelle MCP optionnelle (mode power user) qui agrège les serveurs, charge les schémas à la demande et économise ~98 % de tokens. Installée avec --use-leanproxy.
• garmin-mcp-auth — outil d'authentification OAuth (tokens stockés dans ~/.garminconnect/)

Composants installés

Composant	Rôle	Installation
uv	Gestionnaire Python	curl -LsSf https://astral.sh/uv/install.sh \| sh
garmin-mcp	Serveur MCP Garmin	uv tool install --python 3.12 git+https://github.com/Taxuspt/garmin_mcp
garmin-mcp-auth	Authentification OAuth	via uv run garmin-mcp-auth
leanproxy-mcp	Passerelle MCP (optionnel)	brew tap mmornati/leanproxy-mcp && brew install leanproxy-mcp

Mode direct (défaut)

Le script d'installation enregistre le serveur MCP garmin dans votre IDE avec la liste blanche d'outils :

{
  "mcpServers": {
    "garmin": {
      "command": "garmin-mcp",
      "args": ["stdio"],
      "env": {
        "GARMIN_ENABLED_TOOLS": "get_activities,get_activities_by_date,get_activity,get_activity_fit_data,get_activity_splits,get_activity_typed_splits,get_activity_split_summaries,get_sleep_data,get_hrv_data,get_training_readiness,get_calendar_events,get_courses,get_workouts,get_workout_by_id,get_scheduled_workouts,schedule_workouts,schedule_week,upload_workout,upload_course,create_strength_workout,delete_workout,unschedule_workout,unschedule_workouts,download_activity_file"
      }
    }
  }
}

Pourquoi une liste blanche ?

garmin-mcp expose ~151 outils. Les agents de ce projet n'en utilisent qu'une vingtaine. La liste blanche (GARMIN_ENABLED_TOOLS) réduit fortement la taxe de contexte de chaque requête. Vous pouvez l'ajuster dans install.sh (variable GARMIN_TOOL_WHITELIST).

Mode passerelle (optionnel — power user)

Installez avec --use-leanproxy :

./install.sh --use-leanproxy

Le script configure deux fichiers dans ~/.config/leanproxy/ :

config.yaml

server:
  host: "127.0.0.1"
  port: 8080
  timeout: 300s
  max_batch_size: 100
optimization:
  lazy_loading:
    enabled: true
    stub_tokens: 54
    cache_ttl: 24h
namespaces:
  sport:
    description: "Sport tools"
    servers:
      - garmin
    allowed_clients:
      - "*"
logging:
  level: "info"
  file: ""

leanproxy_servers.yaml

version: "1.0"
servers:
    - name: garmin
      enabled: true
      transport: stdio
      stdio:
        command: garmin-mcp
        args:
            - stdio
        env:
            - GARMIN_ENABLED_TOOLS: "get_activities,get_activities_by_date,get_activity,get_activity_fit_data,get_activity_splits,get_activity_typed_splits,get_activity_split_summaries,get_sleep_data,get_hrv_data,get_training_readiness,get_calendar_events,get_courses,get_workouts,get_workout_by_id,get_scheduled_workouts,schedule_workouts,schedule_week,upload_workout,upload_course,create_strength_workout,delete_workout,unschedule_workout,unschedule_workouts,download_activity_file"
        cwd: .
      timeout: 300s
      connect_timeout: 10s
      idle_timeout: ""

Config existante

Le script ne remplace pas une configuration existante. Si config.yaml ou leanproxy_servers.yaml existent déjà, ils sont conservés.

Authentification

Les tokens Garmin sont stockés dans ~/.garminconnect/ et sont valides environ 6 mois.

Vérifier les tokens

uv run garmin-mcp-auth --verify

Renouveler l'authentification

uv run garmin-mcp-auth

Données accessibles

Les agents accèdent aux outils Garmin directement (mode direct) ou via leanproxy_invoke_tool(server="garmin", tool="...") (mode passerelle) :

• Activités : liste, détails, fichiers FIT
• Santé : HRV, sommeil, stress, fréquence cardiaque au repos
• Calendrier : séances planifiées, push d'entraînements
• Planification : création de séances (course, fractionné, renforcement)

Dépannage

Problème	Solution
garmin-mcp introuvable	uv tool install --python 3.12 git+https://github.com/Taxuspt/garmin_mcp
Tokens expirés	uv run garmin-mcp-auth
leanproxy-mcp introuvable (mode passerelle)	brew tap mmornati/leanproxy-mcp && brew install leanproxy-mcp
Erreur de connexion	Vérifiez que garmin-mcp fonctionne : garmin-mcp stdio

Voir aussi la page Dépannage.