Personal Garmin MCP

Un servidor MCP local para crear y programar entrenamientos estructurados en Garmin Connect mediante endpoints no oficiales de Garmin.

Este es un proyecto personal experimental. Garmin puede cambiar los endpoints, limitar la frecuencia de las solicitudes o revocar una sesión sin previo aviso. No expongas el servidor a Internet sin añadir una autenticación adicional.

Features

• verifica una sesión guardada de Garmin;

• previsualiza el JSON de Garmin sin realizar cambios;

• crea entrenamientos y opcionalmente los añade al calendario;

• lista la biblioteca de entrenamientos y el calendario;

• lee actividades completadas, resúmenes compactos y métricas de vueltas/segmentos;

• lee los datos disponibles de sueño, HRV, Body Battery, Training Readiness y Training Status;

• elimina entrenamientos y quita entrenamientos del calendario;

• admite correr, ciclismo, caminar y senderismo;

• admite pasos por tiempo, distancia y lap button;

• admite repeticiones de intervalos;

• admite objetivos de ritmo, frecuencia cardíaca, potencia y cadencia;

• requiere confirm=true para cada cambio.

Related MCP server: garmin-mcp

Installation

Docker Compose — recomendado

El uso local requiere Docker con soporte de Compose. Construye la imagen desde la raíz del repositorio:

docker compose build

La compilación instala las dependencias de Python con uv estrictamente desde uv.lock.

Ejecuta el inicio de sesión interactivo una vez. La contraseña y el código MFA se introducen directamente en el contenedor y no se almacenan. Los tokens OAuth se guardan en el volumen nombrado privado garmin-mcp_garmin_tokens:

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

Inicia el servidor MCP:

docker compose up -d garmin-mcp
docker compose ps

El endpoint está disponible en http://127.0.0.1:8000/mcp. Para usar un puerto local diferente:

GARMIN_MCP_PORT=8765 docker compose up -d garmin-mcp

Ver los registros o detener el servidor:

docker compose logs -f garmin-mcp
docker compose down

docker compose down conserva los tokens de Garmin. Ejecutar docker compose down -v elimina el volumen y sus tokens.

Instalación local sin Docker

Se requieren Python 3.12+ y uv.

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

Inicio de sesión de una sola vez

uv run garmin-mcp-login

El script solicita interactivamente una dirección de correo electrónico, una contraseña y un código MFA cuando es necesario. La contraseña no se almacena. Los tokens OAuth se guardan en .garmin-tokens/garmin_tokens.json con permisos restringidos. El directorio ya está incluido en .gitignore.

Para almacenar los tokens en otro lugar:

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

MCP local sobre stdio

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

Ejemplo de configuración de cliente MCP:

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

HTTP transmisible para 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

Endpoint: http://127.0.0.1:8000/mcp.

ChatGPT debe poder alcanzar el endpoint a través de HTTPS. Se puede usar un túnel protegido para pruebas personales. No expongas este MVP directamente a Internet: intencionalmente no incluye un servidor de recursos OAuth separado para el acceso al propio servidor MCP.

Ejemplo de argumento 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
          }
        ]
      }
    ]
  }
}

Los valores de ritmo se especifican en segundos por kilómetro: 250 = 4:10/km y 260 = 4:20/km. El servidor los convierte a los valores de m/s que usa Garmin Connect.

Después de previsualizar, llama a create_workout con el mismo objeto, una fecha en formato YYYY-MM-DD y confirm=true.

Contexto de entrenamiento de solo lectura

El servidor expone herramientas compactas de solo lectura para adaptar planes futuros al trabajo completado:

• list_activities lista las actividades en un rango de fechas inclusivo, con un filtro opcional de tipo de actividad de Garmin;

• get_activity_summary devuelve métricas de planificación para una actividad;

• get_activity_splits devuelve métricas compactas de vueltas e intervalos;

• get_recovery_status agrega los datos disponibles de sueño, HRV, Body Battery, Training Readiness y Training Status para una fecha.

Las respuestas de actividad omiten intencionalmente las coordenadas GPS y los detalles del propietario. Las métricas de recuperación varían según el dispositivo Garmin, la cuenta y la fecha. Una fuente faltante se devuelve como no disponible y no hace que falle toda la solicitud de recuperación.

Comprobaciones

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

Las pruebas unitarias no contactan con Garmin y no requieren credenciales.

Limitaciones importantes

• Esto no es una API oficial de Garmin Training.

• Los inicios de sesión frecuentes pueden recibir respuestas HTTP 429; reutiliza los tokens guardados.

• Los tokens proporcionan acceso a Garmin Connect y deben protegerse como una contraseña.

• Si la creación se realiza correctamente pero la programación falla, la herramienta devuelve created_not_scheduled y workout_id; el entrenamiento creado permanece en la biblioteca.

• Antes del uso regular, prueba un entrenamiento sencillo en Garmin Connect y en el modelo de reloj específico.