Garmin Connect MCP server

Un servidor MCP para entrenamiento de fuerza en Garmin Connect. Diseña una sesión conversando con un asistente de IA, envíala a tu reloj y lee lo que realmente levantaste.

No oficial. No está afiliado, avalado ni respaldado por Garmin. Garmin y Garmin Connect son marcas comerciales de Garmin Ltd. Este proyecto habla con los endpoints privados del servicio de entrenamientos de Garmin a través del cliente python-garminconnect invertido. Por lo tanto, Garmin puede cambiarlo o romperlo sin previo aviso. Úsalo bajo tu propia responsabilidad y verifica tus propias obligaciones según los términos de servicio de Garmin.

Todo se ejecuta localmente. Tus credenciales permanecen en tu máquina y solo van a Garmin.

Por qué existe esto

Garmin Connect no permite importar archivos .FIT de entrenamiento: la importación de FIT solo funciona para actividades completadas, no para entrenamientos planificados. Tus opciones son la interfaz web de Connect a mano, o el mismo endpoint privado que usa la aplicación web. Esto toma la segunda ruta y le pone una interfaz MCP, para que un entrenamiento pueda salir de una conversación en lugar de veinte minutos de clics.

Herramientas

delete_workout es la única herramienta destructiva.

Configuración

Requiere Python 3.12 o posterior (garminconnect 0.3.x lo necesita).

git clone https://github.com/YOUR-USERNAME/garmin-mcp.git
cd garmin-mcp
./setup.sh

setup.sh crea .venv/ en el directorio del proyecto, instala las dependencias y copia .env.example a .env. No se instala nada a nivel del sistema. Si tu Python más reciente aún no tiene ruedas para alguna dependencia, cámbialo:

PYTHON=python3.13 ./setup.sh

Completa .env con tu inicio de sesión de Garmin y luego autentícate una vez:

./.venv/bin/python garmin_login.py

Este paso es interactivo a propósito. Garmin puede pedir un código MFA, y el servidor MCP no tiene terminal para preguntar; simplemente se colgaría. El inicio de sesión guarda los tokens en ~/.garminconnect, y el servidor los reutiliza silenciosamente a partir de entonces. Vuelve a ejecutarlo solo si el servidor indica que la sesión ha expirado.

Verifica la compilación sin tocar la red:

./.venv/bin/python garmin_mcp.py --self-test

Conéctalo a un cliente

Claude Desktop

Añade a claude_desktop_config.json — en macOS en ~/Library/Application Support/Claude/, en Windows en %APPDATA%\Claude\:

{
  "mcpServers": {
    "garmin": {
      "command": "/absolute/path/to/garmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/garmin-mcp/garmin_mcp.py"]
    }
  }
}

Usa rutas absolutas y el intérprete del entorno virtual, no un python a secas: la aplicación no hereda el PATH de tu shell. Reinicia la aplicación después.

Cualquier otro cliente

Es un servidor estándar de stdio MCP, por lo que cualquier cliente funciona. Para depurar fuera de uno:

npx @modelcontextprotocol/inspector ./.venv/bin/python garmin_mcp.py

Programas

Un programa es un archivo JSON en programs/ que describe una plantilla de varios días. sync_program envía cada entrenamiento de él, coincidiendo por nombre: los entrenamientos existentes se actualizan en su lugar, los nuevos se crean. Consulta programs/example.json para ver una plantilla comentada.

{
  "name": "Example Upper/Lower",
  "workouts": [
    {
      "name": "[EX] Upper A",
      "warmup": "Two or three ramp-up sets.",
      "blocks": [
        {
          "repeat": 4,
          "steps": [
            { "exercise": "Barbell Bench Press", "reps": 5, "weight_kg": 60,
              "note": "4x5-7. Add 2.5kg once you hit 7 on every set." },
            { "rest_seconds": 180 }
          ]
        }
      ]
    }
  ]
}

Un bloque es un grupo repetible que se ejecuta repeat veces. Un paso es un ejercicio (exercise y reps, opcionalmente weight_kg y note) o un descanso (rest_seconds). Un superset es un bloque con dos ejercicios: descanso corto entre ellos y descanso largo al final. Omite weight_kg para trabajo con peso corporal. Omite warmup para el calentamiento predeterminado, o ponlo en "" para ninguno.

programs/*.json está en .gitignore excepto el ejemplo, para que tu propio entrenamiento nunca llegue a un commit.

Cosas que te morderán

Garmin borra silenciosamente los nombres de ejercicios no reconocidos. La subida devuelve 200 y el ejercicio aparece sin nombre en el reloj a mitad de sesión. Por eso existe search_exercises y por eso cada nombre se resuelve contra el catálogo antes de subirlo. Los nombres mostrados tienen guiones de formas que nadie escribe — "Rope Press-down", "Close-grip Chin-up" — así que la búsqueda normaliza la puntuación y entiende abreviaturas como "db", "bb", "ohp", "rdl".

Las dos mitades de la API no se ponen de acuerdo sobre las unidades de peso. El servicio de entrenamientos toma el peso en kilogramos, aunque weightUnit lleve "factor": 1000.0 — los datos de actividad (lo que levantaste) se reportan en gramos. Ambos se manejan; no corrijas ninguno.

La verificación de ida y vuelta no detecta errores de unidades. Compara lo que Garmin almacenó con lo que se envió, y Garmin almacena fielmente lo que envías. El control pasó y Connect mostraba "75.000 kg" cuando eran gramos. Revisa el entrenamiento en Connect.

Actualizar, no borrar y recrear. Mantener el ID del entrenamiento hace que el reloj lo trate como una edición. Recrearlo hace que descarte los antiguos y descargue nuevos, lo que produce duplicados obsoletos.

El 429 y el 401 se parecen. Garmin limita la tasa de inicios de sesión por IP, de forma agresiva. Cuando el primer transporte de login se estrangula, garminconnect informa un 401 engañoso. Si ves un 429 justo antes, es limitación de tasa: espera 30–60 minutos, y no reintentes en bucle, porque eso alarga el bloqueo. Para depurar: garmin_login.py --verbose.

Licencia

MIT

Basado en python-garminconnect y en el SDK de Python de MCP.

garmin_mcp.py       the server — tool definitions
garmin_core.py      auth, payload building, verification, set parsing
garmin_login.py     one-time interactive login (MFA lives here)
programs/           multi-day templates as JSON
setup.sh            creates .venv and installs dependencies

Licencia

MIT

Construido sobre python-garminconnect y el SDK de Python de MCP.