Garmin Read-Only MCP

Una integración deliberadamente limitada de Garmin Connect para uso local con Hermes Agent. Sincroniza resúmenes seleccionados de Garmin en una caché SQLite de solo propietario, luego sirve solo esa caché normalizada a través de tres herramientas MCP de solo lectura.

Este proyecto utiliza el cliente python-garminconnect mantenido por la comunidad y los endpoints no documentados de Garmin Connect. No está afiliado ni respaldado por Garmin. Los endpoints pueden cambiar, y el acceso automatizado puede conllevar riesgos para la cuenta o los términos de uso. El programa oficial Garmin Connect Developer Program sigue siendo la ruta preferida para integraciones comerciales aprobadas.

Modelo de seguridad

El diseño separa el acceso a la red del proceso MCP:

1. garmin-readonly-auth realiza un inicio de sesión interactivo único en una terminal local. La entrada de contraseña y MFA está oculta y nunca se acepta como argumentos de comando.

2. garmin-readonly-sync carga el material de sesión local reutilizable, obtiene una ventana de fechas acotada, elimina los campos de origen y escribe resúmenes normalizados en SQLite.

3. garmin-readonly-mcp no importa ni el cliente de Garmin ni el material de sesión. Solo lee la caché SQLite normalizada y rechaza las cachés que sean enlaces simbólicos, no regulares, no propiedad del usuario actual, o accesibles por el grupo/otros usuarios.

El directorio de estado predeterminado es:

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

Establezca la variable de entorno no secreta GARMIN_READONLY_HOME para usar otra raíz. Nunca coloque el directorio de estado dentro del repositorio.

Related MCP server: garmin-mcp-local

Alcance de los datos

La caché y MCP exponen solo:

• Calorías totales diarias, activas y BMR/en reposo

• Pasos y frecuencia cardíaca en reposo cuando estén disponibles

• Tipo de actividad, hora de inicio, duración, distancia y calorías

• Duración/puntuación del sueño, Body Battery, HRV/estado nocturno y preparación para el entrenamiento cuando estén disponibles

Excluyen deliberadamente:

• Perfil de Garmin y datos sociales

• Identificadores de cuenta e IDs de actividad

• Detalles del dispositivo

• Coordenadas GPS, rutas y archivos FIT/GPX/TCX

• Peso y composición corporal

• Respuestas sin procesar de Garmin

• Operaciones de carga, actualización, programación o eliminación

• Acceso genérico o arbitrario a la API de Garmin

Los valores de calorías de Garmin son contexto de actividad, no una orden para aumentar la ingesta de alimentos.

Requisitos

• Linux u otro entorno similar a Unix con permisos de archivos privados

• Python 3.12+

• uv

• Una cuenta de Garmin Connect

Instalar

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

Autenticar localmente

Ejecute esto en una terminal local privada—no en Telegram, chat, historial de shell o una pantalla compartida:

uv run garmin-readonly-auth

El comando pregunta localmente por el correo electrónico, la contraseña oculta y el MFA oculto si Garmin lo requiere. Almacena material de sesión reutilizable pero no la contraseña.

Sincronizar

El valor predeterminado sincroniza hoy y ayer:

uv run garmin-readonly-sync

Se puede solicitar una ventana histórica limitada:

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

--days debe estar entre 1 y 31. Los errores del proveedor se reemplazan con un mensaje público fijo para que las respuestas sin procesar de Garmin y los detalles de autenticación no se repitan.

Ejecutar el servidor MCP

Después de al menos una sincronización exitosa:

uv run garmin-readonly-mcp

El servidor stdio expone exactamente:

• get_daily_activity(date: YYYY-MM-DD)

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

• get_recovery_summary(date: YYYY-MM-DD)

Los esquemas de las herramientas rechazan argumentos no declarados.

Conectar a Hermes Agent

Use el comando MCP de Hermes en lugar de editar config.yaml manualmente:

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

Reinicie Hermes después de agregar el servidor para que sus herramientas sean descubiertas. No se pasan credenciales ni rutas de tokens de sesión a la configuración MCP; utiliza la raíz de estado predeterminada privada. Si GARMIN_READONLY_HOME está personalizado, pase solo esa configuración no secreta con hermes mcp add ... --env GARMIN_READONLY_HOME=/private/path.

Desarrollo y verificación

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

La implementación se desarrolló primero con pruebas fallidas. CI ejecuta las mismas compuertas de prueba, lint, verificación de tipos y auditoría de dependencias.

Limitaciones

• Los endpoints de Garmin Connect están diseñados mediante ingeniería inversa y pueden romperse sin previo aviso.

• Garmin puede limitar la tasa, desafiar o bloquear clientes automatizados.

• Algunos campos de recuperación no están disponibles en algunos dispositivos o fechas y devuelven null.

• La caché local es una instantánea; programe garmin-readonly-sync por separado si se necesitan datos más recientes.

• Este proyecto no modifica automáticamente los objetivos de calorías ni proporciona asesoramiento médico.

Consulte SECURITY.md para conocer el manejo de credenciales y la notificación de vulnerabilidades.