Garmin Connect Personal MCP Server
Connects AI agents to the Garmin Connect Personal API to retrieve and analyze Garmin activity, biometric, training, recovery, sleep, HRV, and wellness data. Provides tools for listing activities, fetching activity summaries and time-series details, viewing workouts, aggregating activity stats over date ranges, retrieving heart rate zones and VO₂ Max trends, and combining sleep, HRV, Body Battery, stress, and daily wellness metrics; also includes a generic authenticated GET tool for other Garmin Personal API endpoints.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
⌚⚡ Garmin Connect Personal MCP Server
** Telemetría deportiva en tiempo real para Agentes de IA mediante el Model Context Protocol (MCP) **
Transformando datos biométricos crudos en inteligencia accionable: este servidor MCP conecta agentes de IA directamente con la API oficial Garmin Connect Personal (personal.connectapi.garmin.com) sin scraping, sin exponer contraseñas y con latencia mínima.
Arquitectura • Dashboard Biométrico Real • Catálogo de Herramientas MCP • Instalación y Configuración • Casos de Uso con IA
🧠 El Problema y la Solución
La mayoría de las integraciones con Garmin Connect dependen de librerías no oficiales que simulan inicios de sesión web (screen scraping), rompiéndose con frecuencia ante bloqueos de Cloudflare o MFA.
garmin-mcp adopta un enfoque de ingeniería limpia sobre la API oficial Garmin Connect Personal:
Zero-Trust Key Isolation: Lee una clave personal autogenerada (
GCDC_...) desde un archivo local aislado (.api-key.k), fuera del control de versiones y nunca expuesta en el contexto del LLM.Intercambio OAuth2/JWT con Caché en Memoria: Negocia automáticamente un Bearer Token temporal firmado por
diauth.garmin.comy lo mantiene en caché durante su ciclo de vida, renovándolo de forma transparente ante respuestas401 Unauthorized.Concurrencia Asíncrona (
asyncio.gather+httpx): Agrega en paralelo múltiples microservicios de Garmin (activity-service,biometric-service,metrics-service,sleep-service,hrv-service,wellness-service) en una sola llamada de herramienta.
Related MCP server: Garmin Workouts MCP Server
🏗️ Arquitectura e Ingeniería
sequenceDiagram
autonumber
participant AI as 🤖 Agente IA (Antigravity / Claude)
participant MCP as ⚡ garmin_mcp_server.py (Stdio)
participant Key as 🔐 .api-key.k (Local Vault)
participant Auth as 🛡️ Garmin Auth Service
participant API as 📡 Garmin Personal API
AI->>MCP: JSON-RPC Call (ej. get_training_metrics)
alt Token no existente o expirado en caché
MCP->>Key: Lee clave GCDC_... localmente
MCP->>Auth: POST /personalapitoken-service/.../token (Header: ApiKey)
Auth-->>MCP: JWT Bearer Token (24h TTL)
MCP->>MCP: Almacena JWT en caché en memoria (23h)
end
par Consultas Asíncronas en Paralelo (httpx.AsyncClient)
MCP->>API: GET /biometric-service/heartRateZones/v2
MCP->>API: GET /metrics-service/metrics/maxmet/daily/{start}/{end}
end
API-->>MCP: Telemetría JSON
MCP-->>AI: Respuesta estructurada y optimizada para ventana de contexto📊 Telemetría Real y Estado Físico
Datos reales extraídos en vivo por este servidor MCP desde mi cuenta de Garmin Connect sobre un bloque de 50 sesiones de entrenamiento:
🫀 Perfil Fisiológico Actual
Indicador Biométrico | Valor Actual | Referencia / Configuración |
VO₂ Máximo Estimado |
| Precisión registrada: |
Frecuencia Cardíaca en Reposo (RHR) |
| Base cardiovascular en reposo |
Frecuencia Cardíaca Máxima Configurada |
| Pico real registrado en piscina: |
Volumen Total (Últimas 50 sesiones) |
|
|
🔥 Configuración de Zonas de Frecuencia Cardíaca (heartRateZones/v2)
Zona 1 │ Calentamiento │ 98 – 116 ppm ░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 50% - 60% FC Máx
Zona 2 │ Base Aeróbica │ 117 – 136 ppm ░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒ 60% - 70% FC Máx
Zona 3 │ Aeróbico │ 137 – 155 ppm ░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒ 70% - 80% FC Máx ◄ Zona media habitual en nado (155 ppm)
Zona 4 │ Umbral Anaeróbico │ 156 – 175 ppm ░░░░░░░░░░░░░░▒▒▒▒▒▒ 80% - 90% FC Máx
Zona 5 │ Esfuerzo Máximo │ 176 – 195+ ppm ░░░░░░░░░░░░░░░░░███ 90% - 100% FC Máx🏅 Desglose por Disciplina (Últimas 50 Actividades)
Disciplina | Sesiones | Distancia Acumulada | Tiempo Activo | Calorías | FC Media | FC Máx Registrada |
🏊♂️ Natación en Piscina ( | 30 | 67.62 km | 26 h 07 min | 18,673 kcal | 155 ppm | 207 ppm |
🏋️♂️ Funcional & Multideporte ( | 10 | 15.37 km | 5 h 22 min | 2,201 kcal | 113 ppm | 176 ppm |
⚡ HIIT & Fuerza ( | 6 | — | 2 h 16 min | 1,483 kcal | 135 ppm | 184 ppm |
🏃♂️ Running & Cinta ( | 3 | 16.24 km | 2 h 00 min | 1,455 kcal | 156 ppm | 179 ppm |
🥾 Trekking / Caminata ( | 1 | 4.37 km | 1 h 12 min | 404 kcal | 109 ppm | 158 ppm |
TOTALES | 50 | 103.60 km | 36 h 57 min | 24,216 kcal | 144 ppm | 207 ppm |
⏱️ Muestra de Sesiones Recientes Consultadas vía MCP
Fecha | Actividad | Distancia | Duración | Ritmo / Intensidad | FC Media / Máx | Energía |
| 🥾 Punilla Caminar |
|
| Zona 1-2 Recuperación |
|
|
| 🏊♂️ Natación en piscina |
|
|
|
|
|
| 🏊♂️ Natación en piscina |
|
| Técnica + Series Aeróbicas |
|
|
| 🏊♂️ Natación en piscina |
|
|
|
|
|
| 🏊♂️ Natación en piscina |
|
|
|
|
|
| ⚡ HIIT | — |
| Bloque metabólico explosivo |
|
|
| 🏊♂️ Natación en piscina |
|
| Fondo aeróbico + sprints Z5 |
|
|
🛠️ Catálogo de Herramientas MCP (Tools)
El servidor expone 8 herramientas especializadas diseñadas para optimizar el consumo de tokens del LLM (por ejemplo, filtrando polilíneas GPS crudas cuando no se requieren):
Herramienta MCP | Microservicio Garmin | Capacidad Analítica |
|
| Búsqueda paginada de entrenamientos con filtros por deporte ( |
|
| Resumen profundo ( |
|
| Series temporales punto a punto (FC, ritmo, potencia, cadencia, SWOLF) con muestreo ajustable ( |
|
| Desglose de bloques e intervalos programados asociados a una sesión. |
|
| Agregación estadística de carga y volumen entre dos fechas ( |
|
| Consulta concurrente de zonas de frecuencia cardíaca ( |
|
| Fusión paralela de 4 endpoints de salud: Sueño, VFC (HRV), Body Battery y Estrés/Pasos diarios. |
|
| Cliente |
🚀 Instalación y Despliegue
1. Requisitos previos
Python 3.12+
Una Personal API Key generada desde tu cuenta en Garmin Connect Web (Profile & Account → Settings → Personal API Key).
2. Configuración del entorno local
# 1. Clonar el repositorio
git clone https://github.com/guillealonso/garmin-mcp.git
cd garmin-mcp
# 2. Crear y activar el entorno virtual
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 3. Instalar dependencias
pip install -r requirements.txt
# 4. Guardar tu clave personal de Garmin (excluida en .gitignore)
Set-Content -Path ".api-key.k" -Value "GCDC_tu_clave_personal_aqui" -NoNewline3. Registro en Antigravity / Claude Desktop (mcp_config.json)
Agrega el servidor en tu archivo mcp_config.json (en Antigravity: ~/.gemini/config/mcp_config.json):
{
"mcpServers": {
"garmin-local-mcp": {
"command": "c:\\ruta\\a\\garmin-mcp\\.venv\\Scripts\\python.exe",
"args": [
"c:\\ruta\\a\\garmin-mcp\\garmin_mcp_server.py"
]
}
}
}💬 Prompts y Análisis Inteligente
Una vez conectado el MCP a tu agente de IA, puedes realizar análisis fisiológicos complejos en lenguaje natural:
🧪 Análisis de eficiencia en natación "Compara mis últimas 10 sesiones de natación en piscina: ¿cómo ha evolucionado mi ritmo por cada 100 metros en relación con mi frecuencia cardíaca media?"
🔋 Auditoría de carga vs. recuperación "Cruza mis entrenamientos de las últimas 2 semanas con mi Body Battery, nivel de estrés y horas de sueño usando
get_recovery_and_wellness. ¿Qué días entrené con fatiga acumulada?"
📈 Inspección de series temporales "Obtén los detalles punto a punto (
get_activity_details) de mi sesión de natación de 1,880 m y dime en qué tramo alcancé el pico de 192 ppm."
🔒 Seguridad por Diseño
Aislamiento de secretos (
*.ken.gitignore): Ninguna clave ni token se persiste en código fuente ni se expone como herramienta leíble por el modelo.Permisos de Solo Lectura: La integración opera exclusivamente sobre los scopes de lectura de la API Personal (
PERSONAL_API_FITNESS_READ,PERSONAL_API_WELLNESS_READ), garantizando que ningún agente pueda alterar ni eliminar tu historial deportivo.
📄 Licencia
Distribuido bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Explore Garmin activity and health data with your AI assistant.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes Garmin Connect data and workout management to AI agents, supporting tools, resources, and prompts for health data, workout creation, and coaching workflows.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to access Garmin Connect activities, workouts, and workout templates for querying and creating workout plans.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to retrieve and discuss personal fitness activities, training splits, heart-rate zones, and daily health metrics from a Garmin Connect account.MIT
- AlicenseNot gradedqualityBmaintenanceConnects AI agents to Garmin Connect so they can read fitness data (activities, sleep, steps, heart rate, weight, workouts, profile) and schedule or manage Garmin Calendar workouts with an explicit confirmation flow.MIT