garmin-mcp

Un servidor MCP local que expone tus datos de actividad, salud y entrenamiento de Garmin Connect (actividades, HRV, sueño, frecuencia cardíaca, estrés, body battery, training readiness, zonas de FC/potencia, umbral de lactato, FTP, VO2max, récords personales, entrenamientos, entrenamientos programados y planes de entrenamiento) como herramientas dentro de Claude Desktop.

Habla directamente con la API en vivo de Garmin Connect mediante la biblioteca garminconnect. Los datos son de solo lectura — nunca se escribe nada de vuelta a Garmin.

Cómo funciona la autenticación

El inicio de sesión de Garmin ocurre en dos lugares separados a propósito:

• scripts/setup_auth.py — un script interactivo que ejecutas tú mismo en una terminal. Inicia sesión con tu correo electrónico/contraseña, te pide un código MFA si Garmin lo solicita, y guarda el token de sesión resultante en ~/.garmin_mcp/tokens.

• El servidor MCP (src/garmin_mcp/server.py), lanzado sin interfaz gráfica por Claude Desktop, solo carga y refresca silenciosamente ese token en caché. Nunca solicita MFA — Claude Desktop no le proporciona una terminal para pedirlo, y bloquearse en stdin colgaría las llamadas a las herramientas. Si la sesión en caché falta o ha caducado, las llamadas a las herramientas fallan con un error que te indica que vuelvas a ejecutar setup_auth.py.

Tu contraseña de Garmin se almacena en el llavero de macOS (elemento/servicio garmin-mcp, visible en Keychain Access), nunca se escribe en un archivo. Solo se guarda tu correo electrónico de inicio de sesión de Garmin (no es secreto), en ~/.garmin_mcp/config.json.

Configuración

1. Instala las dependencias:

   cd garmin_mcp
   uv sync

2. Ejecuta el inicio de sesión interactivo único:

   uv run python scripts/setup_auth.py

   Introduce tu correo electrónico y contraseña de Garmin Connect (la contraseña se guarda en el llavero para la próxima vez). Introduce el código MFA cuando se te pida. Si se completa correctamente, verás una confirmación y la ruta de la caché del token.

3. Registra el servidor en Claude Desktop editando ~/Library/Application Support/Claude/claude_desktop_config.json y añadiendo (junto a cualquier otra entrada de mcpServers):

   {
     "mcpServers": {
       "garmin": {
         "command": "uv",
         "args": ["run", "--project", "/Users/felix.guiony/Code/Perso/garmin_mcp", "garmin-mcp"]
       }
     }
   }

4. Sal por completo de Claude Desktop (Cmd+Q, no solo cierres la ventana) y vuelve a abrirlo. El icono de herramientas/martillo debería mostrar las herramientas garmin.

Herramientas

Todos los parámetros de fecha aceptan YYYY-MM-DD y su valor por defecto es hoy.

Solución de problemas

Una llamada de herramienta devuelve un mensaje "Garmin session error" / "run setup_auth.py". Tu token de refresco en caché ha caducado o ha sido revocado (esto ocurre de vez en cuando, p. ej., tras un cambio de contraseña o un largo periodo de inactividad). Vuelve a ejecutar:

uv run python scripts/setup_auth.py

Límite de peticiones. Garmin Connect ocasionalmente limitará la velocidad de las peticiones rápidas; la biblioteca subyacente reintenta automáticamente los fallos transitorios, pero si ves un error de límite de peticiones, espera un poco y vuelve a intentarlo.

Verificación del servidor directamente, fuera de Claude Desktop:

uv run mcp dev src/garmin_mcp/server.py

abre el MCP Inspector para que puedas llamar a cada herramienta manualmente y comprobar su salida/esquema.

Estructura del proyecto

garmin_mcp/
  pyproject.toml
  src/garmin_mcp/
    auth.py      # keychain + token-cache helpers
    server.py    # FastMCP server and tool definitions
  scripts/
    setup_auth.py  # interactive one-time/occasional login