Local Garmin Coach MCP

Private, single-user Garmin coaching tools for Codex/ChatGPT desktop and Claude. The server is local stdio only: no Cloudflare, Render, public URL, account service, or hosting cost.

The runtime is based on etweisberg/garmin-connect-mcp at commit 87d0ea059fb67f1ce65ac05100df74c3c3777c84. It keeps the upstream AGPL-3.0 license and Taxuspt attribution in NOTICE.

Requisitos previos

• Node.js 20 o superior

• pnpm 10.14.0

• Una cuenta de Garmin Connect y un reloj sincronizado

Related MCP server: io.github.matisdsp/fartlek

Instalación

cd /home/talvak/Desktop/repos/garmin-coach-mcp
pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm build
pnpm auth

pnpm auth abre un perfil de Chrome visible y dedicado. Inicia sesión manualmente, completa la MFA y luego pulsa Enter en la terminal. La sesión del navegador se guarda en ~/.local/share/garmin-coach/browser-profile. Los valores de CSRF en tiempo de ejecución se leen de la página autenticada actual y nunca se persisten ni se imprimen. Los directorios son 0700, los archivos son 0600, el guardado de contraseñas está desactivado y no se crea ningún archivo de usuario/contraseña.

Capturar el contrato de escritura de perfil de Garmin

Garmin no publica una API estable de escritura de perfil de frecuencia cardíaca. El servidor se niega a adivinarla.

pnpm capture:profile-contract

El comando carga el modelo de aplicación actual de Garmin, le pide que guarde las zonas predeterminadas actuales sin cambios y bloquea el PUT resultante antes de su entrega. Valida la ruta y el cuerpo exacto sin cambios, y luego almacena solo una forma redactada de método/ruta/campos y los ámbitos admitidos en ~/.local/state/garmin-coach/profile-write-contract.json con modo 0600.

Si la forma de Garmin no puede demostrarse, no se guarda ningún contrato y las escrituras de perfil permanecen deshabilitadas.

Conectar Codex y ChatGPT desktop

Compila primero y luego copia config/codex.toml.example en ~/.codex/config.toml, o añade el servidor equivalente a través de Configuración > Servidores MCP de ChatGPT desktop. Codex CLI, la extensión del IDE y ChatGPT desktop comparten la configuración local de MCP en el mismo host.

El ejemplo utiliza:

default_tools_approval_mode = "writes"

Ambas herramientas de aplicación también tienen un approval_mode = "prompt" explícito. Reinicia el cliente después de la configuración y usa /mcp para verificar la conexión.

ChatGPT web no puede iniciar este proceso stdio local. Usa ChatGPT desktop/Codex para las escrituras de Garmin.

Conectar Claude

Combina config/claude.json.example en la configuración MCP de Claude, o ejecuta:

claude mcp add garmin-coach -- /home/talvak/snap/code/current/.local/share/pnpm/node /home/talvak/Desktop/repos/garmin-coach-mcp/dist/index.js

El bloqueo del sistema de archivos permite que solo un cliente local posea el perfil de Chromium de Garmin a la vez. Detén el servidor en un cliente antes de usar el otro.

Herramientas

Flujo de trabajo seguro

1. Llama a get_coaching_snapshot y compáralo con Garmin Connect.

2. Llama a preview_hr_profile_update.

3. Revisa cada campo y aprueba la propuesta/hash canónica exacta.

4. Llama a apply_hr_profile_update; luego sincroniza Garmin y verifica visualmente las zonas del reloj.

5. Llama a preview_training_week para una semana que comienza en domingo.

6. Revisa su evidencia de recuperación, la carga útil completa, las advertencias y el hash.

7. Llama a apply_training_week con la propuesta/hash canónica sin cambios.

8. Llama a verify_training_week y confirma que lunes/viernes son 135-149 bpm; el viernes debe mostrar instrucciones fijas de 12%.

9. Reintenta ambas llamadas de aplicación para demostrar la idempotencia.

El dolor/lesión o la enfermedad bloquean las escrituras de entrenamiento. La recuperación puede mantener, reducir u omitir; nunca aumenta la carga. Los entrenamientos nunca se eliminan automáticamente.

Garmin expone Treadmill como una actividad de reloj dentro de Running, no como un deporte de entrenamiento estructurado. Por lo tanto, el viernes es un entrenamiento compatible con running llamado Incline Walk 12%; inícialo desde la actividad Treadmill del reloj. Su indicación de inclinación 12% y su objetivo de 135-149 bpm siguen siendo explícitos.

Perfil de FC aprobado

Estos valores son provisionales: edad 27, FC en reposo 55, FC máxima estimada 189 y LTHR manual 181. Los indicadores de detección automática se conservan. Los cambios futuros requieren otra vista previa y aprobación.

Verificación

Las pruebas ordinarias son sin conexión y nunca llaman a Garmin:

pnpm test
pnpm lint
pnpm format:check
pnpm typecheck
pnpm build
git diff --check

Consulta spec.md para el comportamiento y docs/architecture.md para los límites de confianza.

Licencia

AGPL-3.0. Consulta LICENSE y NOTICE.