Garmin Connect

Accede a los datos de actividad y la información del plan de entrenamiento de Garmin Connect.

Documentación

garmin-mcp

Servidor MCP (Model Context Protocol) que proporciona datos de running de Garmin Connect a LLMs.

Se integra con clientes MCP como Claude Desktop para realizar análisis de entrenamiento de running, planificación, creación de workouts, etc.

Funciones principales

Consulta de actividades de running - Actividades recientes, consulta por fecha, análisis detallado, datos de splits (47 campos: ritmo, frecuencia cardíaca, cadencia, dinámicas de running, potencia, zonas de FC, GAP, pendiente, stamina, temperatura, etc.)
Análisis de trail running - Análisis de segmentos de pendiente ClimbPro, dificultad por grado, ritmo ajustado por pendiente, detección de correr/caminar, condiciones meteorológicas
Resumen semanal/mensual - Tendencias de volumen, comparación con el mes anterior
Métricas de entrenamiento - VO2max, estado de entrenamiento, disposición para entrenar, predicciones de carrera, umbral de lactato
Frecuencia cardíaca/HRV - FC diaria, variabilidad de la frecuencia cardíaca, distribución de zonas de FC por actividad
Bienestar - Sueño, estrés, Body Battery, SpO2
Récords/objetivos personales - RP, objetivos de fitness
Creación de workouts - Workouts estructurados basados en tiempo/distancia, intervalos, tempo, etc., enviados al reloj Garmin (objetivos de ritmo/FC/cadencia/potencia)
Gestión de zapatillas - Distancia acumulada por par + seguimiento del desgaste
Privacidad - Filtrado automático de PII (nombre del propietario, ID de perfil, coordenadas GPS) en todas las respuestas de la API

Requisitos

Python 3.10+
Gestor de paquetes uv
Cuenta de Garmin Connect

Instalación

git clone https://github.com/leewnsdud/garmin-connect-mcp.git
cd garmin-connect-mcp
uv sync

Autenticación

Se requiere autenticación una sola vez la primera vez.

uv run python scripts/auth.py

Al introducir correo electrónico y contraseña, el token OAuth se guarda en ~/.garminconnect/. Si se usa MFA, aparecerá un aviso para introducir el código.

Si el token caduca, vuelve a ejecutarlo o configura las credenciales en el archivo .env para que se renueve automáticamente.

Integración con Claude Desktop

Añade en ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin-mcp": {
      "command": "/Users/<username>/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/garmin-mcp",
        "run",
        "garmin-mcp"
      ]
    }
  }
}

Debes usar la ruta completa de uv. Verifícalo con which uv.

Tras la configuración, reinicia Claude Desktop para que las herramientas se activen.

Variables de entorno (opcional)

Consulta .env.example para crear el archivo .env.

Variable	Descripción	Valor por defecto
`GARMIN_EMAIL`	Correo electrónico de Garmin Connect	-
`GARMIN_PASSWORD`	Contraseña de Garmin Connect	-
`GARMIN_TOKEN_DIR`	Ruta de almacenamiento del token	`~/.garminconnect`
`GARMINTOKENS`	Token codificado en Base64 (para CI/Docker)	-

Herramientas disponibles (24)

Activities

Herramienta	Descripción	Parámetros principales
`get_recent_activities`	Lista de actividades de running recientes (incluye GAP, RWD)	`count` (por defecto 20, máximo 100)
`get_activities_by_date`	Consulta de actividades de running por rango de fechas	`start_date`, `end_date`
`get_activity_detail`	Información detallada de la actividad (incluye stamina, carga de impacto)	`activity_id`
`get_activity_splits`	Datos de splits por km	`activity_id`
`get_activity_weather`	Condiciones meteorológicas durante la actividad (temperatura, humedad, velocidad del viento)	`activity_id`
`get_activity_typed_splits`	Análisis de segmentos de pendiente ClimbPro (grado, GAP)	`activity_id`

Summary

Herramienta	Descripción	Parámetros principales
`get_weekly_running_summary`	Resumen semanal de running	`end_date`, `weeks` (máximo 12)
`get_monthly_running_summary`	Resumen mensual de running + comparación con el mes anterior	`year`, `month`

Training

Herramienta	Descripción	Parámetros principales
`get_training_status`	Estado de entrenamiento	`date`
`get_training_readiness`	Puntuación de disposición para entrenar	`date`
`get_vo2max_and_fitness`	VO2max + edad de fitness	`date`
`get_race_predictions`	Tiempos estimados en 5K/10K/medio maratón/maratón	Ninguno
`get_lactate_threshold`	FC/ritmo en umbral de lactato	`start_date`, `end_date`

Heart Rate

Herramienta	Descripción	Parámetros principales
`get_heart_rate_data`	Datos de FC diarios	`date`
`get_hrv_data`	Variabilidad de la frecuencia cardíaca (HRV)	`date`
`get_activity_hr_zones`	Distribución de zonas de FC por actividad	`activity_id`

Wellness

Herramienta	Descripción	Parámetros principales
`get_sleep_data`	Datos de sueño	`date`
`get_daily_wellness`	Estrés/Body Battery/SpO2/frecuencia respiratoria	`date`
`get_weekly_wellness_summary`	Tendencias semanales de bienestar	`end_date`, `weeks` (máximo 4)

Records & Goals

Herramienta	Descripción	Parámetros principales
`get_personal_records`	Récords personales (1K~maratón)	Ninguno
`get_goals`	Objetivos de fitness	`status` (active/completed/all)

Workout

Herramienta	Descripción	Parámetros principales
`create_running_workout`	Creación de workouts y carga en Garmin (basados en tiempo/distancia, objetivos de ritmo/FC/cadencia/potencia)	`name`, `steps`, `description`
`get_workouts`	Lista de workouts guardados	`count` (por defecto 20, máximo 100)

Gear

Herramienta	Descripción	Parámetros principales
`get_running_gear`	Lista de zapatillas + distancia acumulada + tasa de desgaste	Ninguno

Guía de creación de workouts

Puedes crear workouts de running estructurados con create_running_workout y sincronizarlos con tu reloj Garmin.

Tipos de Step

Tipo	Descripción
`warmup`	Calentamiento
`interval`	Intervalo (alta intensidad)
`recovery`	Trote de recuperación
`rest`	Descanso completo (parado)
`cooldown`	Enfriamiento
`repeat`	Grupo de repeticiones

Condiciones de finalización (duración del Step)

Campo	Tipo	Descripción	Ejemplo
`duration_seconds`	int	Basado en tiempo	`"duration_seconds": 300` (5 minutos)
`distance_meters`	int	Basado en distancia	`"distance_meters": 1000` (1 km)

Puedes combinar steps basados en tiempo y distancia en un mismo workout.

Tipos de Target

Tipo	Formato del valor	Ejemplo
`pace`	min:seg/km	`"min": "4:30", "max": "4:50"`
`heart_rate`	bpm	`"min": 140, "max": 155`
`cadence`	spm	`"min": 170, "max": 185`
`power`	vatios	`"min": 280, "max": 320`

Opciones

Nota del workout: añade una descripción completa con el parámetro description
Nota del Step: añade "description": "메모" a cada step
Omitir recuperación final: añade "skip_last_rest": true al step de repeticiones

Ejemplo: intervalos de 4x1 km basados en distancia

{
  "name": "4x1km Intervals @4:30",
  "description": "10K 레이스 대비 VO2max 인터벌",
  "steps": [
    {
      "type": "warmup",
      "duration_seconds": 600,
      "description": "가볍게 조깅"
    },
    {
      "type": "repeat",
      "count": 4,
      "skip_last_rest": true,
      "steps": [
        {
          "type": "interval",
          "distance_meters": 1000,
          "target": { "type": "pace", "min": "4:20", "max": "4:40" },
          "description": "목표 페이스 유지"
        },
        {
          "type": "recovery",
          "duration_seconds": 120,
          "description": "천천히 조깅으로 회복"
        }
      ]
    },
    {
      "type": "cooldown",
      "duration_seconds": 600,
      "description": "마무리 조깅"
    }
  ]
}

Consulta la guía detallada de creación de workouts en AGENTS.md y la especificación completa de solicitudes/respuestas de herramientas en TOOL_SPEC.md.

Ejemplos de uso

Puedes usar Claude Desktop de las siguientes maneras:

"Resume mi running de esta semana"
"Analiza la tendencia de volumen semanal de los últimos 3 meses"
"Calcula mis ritmos de entrenamiento según Jack Daniels VDOT basándote en mi VO2max"
"Revisa la distribución de zonas de FC de mis actividades recientes y comprueba si estoy cumpliendo la proporción 80/20"
"Crea un workout de intervalos de 4x1 km para mañana"
"Comprueba si alguna de mis zapatillas necesita ser reemplazada"
"Analiza la correlación entre sueño y disposición para entrenar"
"Analiza mi rendimiento por segmentos de pendiente en mis trail runs recientes"
"Comprueba la proporción caminar/correr en mis trail runs"

Metodologías de entrenamiento de running compatibles

Metodología	Datos utilizados
Jack Daniels VDOT	VO2max, RP, predicciones de carrera
Norwegian Double Threshold	Umbral de lactato, zonas de FC
80/20 Training	Distribución de zonas de FC
Método de Hanson	Volumen semanal/mensual, tendencias de ritmo
Pfitzinger	Volumen semanal, análisis de carreras largas
Análisis de trail/ultra	Segmentos de pendiente ClimbPro, clima, RWD, GAP

Desarrollo

# 코드 수정 후 패키지 재설치
uv sync --reinstall-package garmin-mcp

# Claude Desktop 재시작으로 MCP 서버 반영

Privacidad

Los siguientes campos de información personal se eliminan automáticamente de todas las respuestas de la API de Garmin:

Información del propietario: ownerId, ownerFullName, ownerDisplayName, userId, URL de imagen de perfil
ID de perfil: userProfilePK, userProfileId, profileId, profileNumber
Información del usuario: displayName, fullName, userPro, userRoles
Coordenadas GPS: startLatitude, startLongitude, endLatitude, endLongitude

Este filtrado se procesa de forma recursiva mediante la función strip_pii() de src/garmin_mcp/sanitize.py.

Stack tecnológico

python-garminconnect - Cliente de la API de Garmin Connect
FastMCP - Framework de servidor MCP
uv - Gestor de paquetes de Python
garth - Gestión de tokens OAuth

Licencia

MIT