garmin-mcp

Servidor MCP remoto para Garmin Connect en Cloudflare Workers (nivel gratuito). Puerto completo en TypeScript de taxuspt/garmin_mcp: las 138 herramientas más un passthrough garmin_get (139 en total) y los 5 recursos MCP de plantillas/referencias de entrenamiento.

Módulos: gestión de actividades (21), salud y bienestar (29), entrenamiento y rendimiento (15), entrenamientos + constructores (19), nutrición (14), desafíos/dispositivos/equipo (18), peso/cuerpo/salud femenina/cursos (14), análisis de archivos FIT (4), perfil de usuario (4), passthrough (1).

Autenticación: el servidor es un servidor de autorización OAuth 2.1 (a través de @cloudflare/workers-oauth-provider). Añadirlo a un cliente MCP abre una página del navegador donde introduces tu correo y contraseña de Garmin (y un código MFA si tu cuenta usa 2FA). El Worker ejecuta el flujo de inicio de sesión del widget web SSO de Garmin en el lado del servidor — la única ruta de inicio de sesión que no está bloqueada por bots desde IPs de centros de datos — obtiene un token OAuth1 de larga duración (~1 año), descarta tus credenciales y almacena solo ese token cifrado en la concesión. Luego acuña tokens portadores OAuth2 de corta duración bajo demanda para connectapi.garmin.com. Un respaldo de "pegar un token" (a través del script local a continuación) está oculto detrás de un interruptor de detalles en caso de que Garmin comience a bloquear el inicio de sesión del lado del servidor.

Deploy

1. npm install

2. npx wrangler kv namespace create OAUTH_KV — pega el id en wrangler.jsonc

3. npx wrangler deploy

Related MCP server: Garmin Open MCP

Connect a client

claude mcp add garmin --transport http https://garmin-mcp.<your-subdomain>.workers.dev/mcp

Claude Code abre la página de autorización en tu navegador; sigue sus dos pasos. claude.ai web: Configuración → Conectores → Añadir conector personalizado con la misma URL. Claude Desktop y otros clientes solo-stdio: mcp-remote también maneja el flujo OAuth.

El acceso es solo OAuth — no hay ruta de cabecera sin procesar. Cada solicitud /mcp está controlada por un token de acceso emitido por el proveedor, y un token de acceso se acuña solo al completar el flujo de inicio de sesión.

Locking to your own account

Establece OWNER_GARMIN_IDS en wrangler.jsonc a tu displayName de Garmin (el valor que devuelve get_user_profile) — una lista de permitidos separada por comas. Cualquier inicio de sesión para una cuenta de Garmin que no esté en la lista se rechaza en el paso de autorización, por lo que los extraños no pueden usar tu implementación incluso con sus propias credenciales válidas de Garmin. Déjalo vacío para permitir cualquier cuenta de Garmin.

Deviations from the original (remote/serverless adaptations)

• download_activity_file devuelve el contenido del archivo en línea (fit como base64, gpx/tcx/csv como texto, con límite de tamaño) en lugar de escribir en el disco local; set_fit_download_dir es un no-op documentado.

• upload_course toma gpx_content (texto XML GPX) en lugar de una ruta de archivo local.

• get_activity_fit_data cubre sesión/vueltas/registros + análisis de potencia (NP, VI, curva de potencia, W/kg); los análisis de cambio Di2, detección de ascensos y HRV del original no se han portado.

• Presupuesto de sub-solicitudes del nivel gratuito (~50/invocación): get_training_load_trend limitado a 45 días (antes 90), get_power_duration_curve a 15 actividades (antes 20), get_hrv_trend usa el endpoint de rango en una sola llamada, bucles de paginación de objetivos/pasos/menstruales limitados.

• Las herramientas devuelven objetos JSON en lugar de cadenas pre-serializadas; los errores aparecen como errores de herramienta MCP.

Notes

• El token de Garmin se almacena cifrado dentro de la concesión en Workers KV; cuando expira (~1 año), las llamadas a herramientas comienzan a fallar — vuelve a autenticar el servidor en tu cliente para ejecutar el flujo de nuevo.

• Los tokens de acceso son credenciales de portador: quien tenga uno válido tiene tus datos hasta que expire, por lo que la seguridad depende de que tu cliente MCP mantenga su token almacenado en secreto.

• Desarrollo local: npm run dev, luego apunta un cliente a http://localhost:8787/mcp.