garmin-mcp

Un pequeño servidor MCP que le da a Claude Desktop acceso de solo lectura a los datos de running, entrenamiento de fuerza y calorías de Garmin Connect. Hay tres herramientas y su configuración lleva aproximadamente quince minutos.

Construí esto porque quería hacer seguimiento del progreso, entre otras cosas, y analizar algunos datos de mi propio entrenamiento (por ejemplo, cómo ha cambiado mi ritmo de carrera suave, o qué levanté los días que también corrí) sin exportar CSV manualmente. Se comunica directamente con la API de Connect de Garmin, por lo que no hay ningún servicio de terceros en el medio y no se sube nada a ningún lado.

Las herramientas

• list_runs(limit, start): fecha, tipo de carrera, distancia, tiempo, ritmo promedio, frecuencia cardíaca promedio y máxima, cadencia, temperatura. También cubre carreras en cinta.

• list_strength(limit, start): fecha, nombre de la sesión, duración, series, repeticiones, calorías brutas y activas, frecuencia cardíaca promedio y máxima.

• daily_calories(days, end): total por día, calorías activas y BMR, más pasos y frecuencia cardíaca en reposo.

start es un desplazamiento de filas y end es una fecha, por lo que Claude puede navegar hacia atrás a través de años de historial en lugar de solo las últimas entradas.

Todo es de solo lectura. La biblioteca subyacente (garth-ng) sí expone endpoints de escritura, pero nada aquí los llama: eso es lo único que hace que esto sea seguro, ya que los propios tokens otorgan acceso completo a la cuenta.

Requisitos

Python 3.12+, uv, Claude Desktop y una cuenta de Garmin Connect. Los comandos a continuación asumen un shell Unix, por lo tanto macOS o Linux; Windows también funciona, pero las rutas difieren. Claude Desktop se ejecuta en macOS, Windows y Linux (beta, en Ubuntu y Debian). Esto no funcionará en la aplicación móvil de Claude ni en claude.ai, porque un servidor stdio local no tiene una URL a la que puedan conectarse.

Configuración

1. Cambia tu contraseña de Garmin por una que no uses en ningún otro lugar, ya que estás a punto de escribirla en un script.

2. Clona e instala:

git clone https://github.com/SuvirRathore/garmin-mcp-public.git
cd garmin-mcp-public
uv sync

3. Autentícate una vez. Esto intercambia tu contraseña por tokens OAuth guardados en ~/.garth, después de lo cual la contraseña nunca más se necesita:

cd garmin-mcp-public
uv run auth_setup.py

Ingresa tu código MFA si se te solicita. El token OAuth1 dura aproximadamente un año y el OAuth2 se renueva solo, por lo que esto es aproximadamente una tarea anual. Trata ~/.garth como una credencial: cualquiera que lo tenga puede leer toda tu cuenta de Garmin.

4. Prueba las herramientas directamente, antes de involucrar a Claude. Un fallo aquí es un problema de autenticación o endpoint, no un problema de MCP, y es mucho más rápido depurar a este nivel que a través de los registros de Desktop:

cd garmin-mcp-public
uv run python -c "import server; print(server.list_runs(3))"
uv run python -c "import server; print(server.list_strength(3))"
uv run python -c "import server; print(server.daily_calories(7))"

5. Encuentra las dos rutas absolutas que necesita la configuración:

cd garmin-mcp-public
which uv
pwd

6. Crea o edita el archivo de configuración de Claude Desktop y pega el bloque a continuación, reemplazando las dos rutas con la salida del paso 5. Pegar tus rutas reales también elimina ambas instancias de YOUR_USERNAME. El archivo se encuentra en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS y %APPDATA%\Claude\claude_desktop_config.json en Windows; en la beta de Linux, consulta la documentación de Claude Desktop de Anthropic para la ubicación actual.

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/garmin-mcp-public",
               "run", "server.py"]
    }
  }
}

Ambas rutas deben ser absolutas. Desktop inicia el servidor con un PATH mínimo, por lo que un uv simple falla incluso si funciona en tu shell. Si ya tienes otros servidores configurados, agrega la entrada garmin junto a ellos en lugar de reemplazar el objeto. Si editas este archivo en TextEdit, desactiva primero las comillas inteligentes: las comillas curvas son JSON no válido.

7. Cierra Claude Desktop por completo (Cmd-Q, no solo la ventana) y vuelve a abrirlo. La configuración solo se lee al iniciar. Luego pregúntale algo como "muéstrame mis últimas cinco carreras y mi quema de calorías esta semana" y aprueba las llamadas a las herramientas.

Si no funciona

Valida el JSON primero, luego lee el stderr del servidor. Estas rutas son las de macOS; ajústalas para tu plataforma:

cd garmin-mcp-public
uv run python -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
tail -50 ~/Library/Logs/Claude/mcp-server-garmin.log

Errores en cada llamada generalmente significan que los tokens expiraron: vuelve a ejecutar auth_setup.py. El diálogo "agregar conector personalizado" dentro de Claude no es relevante aquí, ya que espera una URL HTTPS remota.

Notas para cualquiera que extienda esto

La API de Connect de Garmin no está documentada y los nombres de sus campos varían, por lo que cuando algo regresa vacío, inspecciona un objeto real en lugar de adivinar. Guarda esto como probe.py en el repositorio y ejecútalo con uv run probe.py, en lugar de pegarlo en un shell:

import garth

garth.resume("~/.garth")
a = garth.connectapi(
    "/activitylist-service/activities/search/activities",
    params={"start": 0, "limit": 1},
)[0]
print(sorted(a))

Dos comportamientos que vale la pena conocer antes de agregar una herramienta. El filtro activityType solo acepta categorías principales: running funciona e incluye silenciosamente treadmill_running, mientras que strength_training devuelve HTTP 400 y debe solicitarse como fitness_equipment y luego filtrarse en Python. Y cada actividad tiene alrededor de cien campos, así que redúcelos al puñado que necesitas: devolver el JSON sin procesar de Garmin inunda la ventana de contexto en cada llamada.

Mantén el número de herramientas pequeño por la misma razón. Tres herramientas enfocadas con docstrings descriptivos funcionan mejor que una docena de vagas, porque los docstrings son lo que Claude lee al elegir qué herramienta llamar.

Licencia MIT.