Garmin Training MCP

Servidor MCP que conecta Claude con tu cuenta de Garmin Connect para que Claude pueda ver tus actividades, tu sueño y tus datos de recuperación, y con eso crear y adaptar día a día tu plan de entrenamiento (running, natación, ciclismo, fuerza) según tu meta.

Modos de uso

Modo	Transporte	Dónde corre	Ventaja
Local	stdio	Tu ordenador, con Claude Desktop	Cero infraestructura, cero latencia
VPS (Dokploy)	HTTP	Tu VPS, accesible por HTTPS	Accesible desde Claude Desktop, Claude Code, móvil...

Puedes usar ambos simultáneamente: el local para uso rápido en el PC, el VPS para cuando estés fuera o desde el móvil.

---

1. Instalación

cd garmin-training-mcp
python3 -m venv venv
source venv/bin/activate        # en Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Credenciales de Garmin

La primera vez que el servidor se conecte necesita tu email y contraseña de Garmin Connect (las mismas que usas en la app). Después de ese primer login, el servidor guarda un token de sesión en ~/.garmin_mcp/tokens y no vuelve a pedir credenciales (hasta que el token caduque).

export GARMIN_EMAIL="tu_email@ejemplo.com"
export GARMIN_PASSWORD="tu_contraseña"

3. Modo local (stdio con Claude Desktop)

3.1 Configurar Claude Desktop

Abre (o crea) el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin-training": {
      "command": "/ruta/absoluta/a/garmin-training-mcp/venv/bin/python3",
      "args": ["/ruta/absoluta/a/garmin-training-mcp/server.py"],
      "env": {
        "GARMIN_EMAIL": "tu_email@ejemplo.com",
        "GARMIN_PASSWORD": "tu_contraseña"
      }
    }
  }
}

Reinicia Claude Desktop. Verás "garmin-training" en las herramientas disponibles.

---

4. Modo VPS con Dokploy

4.1 Subir el código a GitHub

cd garmin-training-mcp
git init && git add -A && git commit -m "initial"
git remote add origin https://github.com/TU_USUARIO/garmin-training-mcp.git
git push -u origin main

4.2 Crear el proyecto en Dokploy

1. En tu VPS con Dokploy: Projects → Create Project → nombre garmin-training
2. Applications → Deploy from GitHub → selecciona el repo
3. Build Settings: Dokploy detecta el Dockerfile automáticamente. Si no:
   • Build Pack: Dockerfile
   • Dockerfile path: Dockerfile
4. Puerto: 8080

4.3 Variables de entorno en Dokploy

En tu proyecto → Environment → añade:

GARMIN_EMAIL=tu_email@example.com
GARMIN_PASSWORD=tu_contraseña
SUPABASE_URL=https://tu-proyecto.supabase.co    # opcional
SUPABASE_KEY=tu_clave_anon                        # opcional
MCP_PORT=8080

⚠️ Si usas Supabase, crea primero las tablas (ver sección más abajo).

4.4 Dominio + HTTPS

1. En Dokploy → Domains → añade tu dominio (ej: garmin.tudominio.com)
2. Dokploy configura SSL automáticamente con Let's Encrypt
3. Tu MCP server queda accesible en https://garmin.tudominio.com/mcp/

4.5 Conectar Claude al VPS

En claude_desktop_config.json (o .claude/settings.json para Claude Code):

{
  "mcpServers": {
    "garmin-training": {
      "transport": {
        "type": "streamable-http",
        "url": "https://garmin.tudominio.com/mcp/"
      }
    }
  }
}

Reinicia Claude Desktop. Las mismas tools estarán disponibles, pero ahora corriendo en tu VPS.

4.6 Probar la conexión

curl -X POST https://garmin.tudominio.com/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

---

5. Cómo usarlo con Claude

Ejemplos de cosas que puedes pedirle a Claude una vez conectado:

• "Mi meta es correr una media maratón en menos de 1h50 el 15 de noviembre. Entreno 4 días por semana. Créame un plan."
• "Buenos días, ¿qué toca hoy?" → Claude usará get_daily_briefing
• "¿Puedo hacer series hoy o mejor lo dejo suave?" → get_training_recommendation
• "Ayer nadé 2000m, ¿cómo voy?" → get_recent_activities / get_activity_detail
• "He dormido fatal esta semana, ajusta el plan" → get_sleep + save_training_plan
• "¿Cómo entrené el mes pasado?" → query_activities_by_date_range

6. Herramientas (tools) que expone el servidor

Tool	Para qué sirve
get_recent_activities	Actividades de los últimos N días
get_activity_detail	Detalle + parciales de una actividad concreta
get_sleep	Sueño (score, fases, horas) de los últimos N días
get_recovery	HRV, FC reposo, estrés, Body Battery, training readiness
get_fitness_status	Estado de forma general y predicciones de marca
query_activities_by_date_range	Actividades entre dos fechas concretas
get_training_load	Minutos entrenados por semana y ratio ACWR
get_training_recommendation	Veredicto de "¿qué puedo hacer hoy?" con razones
import_strava_csv	Importa el activities.csv del export de Strava
get_strava_activities	Actividades importadas de Strava
get_combined_activities	Garmin + Strava juntas, ordenadas por fecha
get_goal / set_goal	Leer / definir tu meta
get_training_plan / save_training_plan	Leer / guardar el plan
get_adaptation_journal	Histórico de ajustes al plan
get_exercise_library	Ejercicios de fuerza/core reales
log_strength_session	Registra una sesión de gimnasio
get_strength_history	Histórico de sesiones de fuerza
get_daily_briefing	Resumen todo-en-uno para decidir el ajuste del día

7. Multi-dispositivo con Supabase (opcional)

Por defecto, el objetivo/plan/diario/histórico se guardan en JSON local. Si defines SUPABASE_URL + SUPABASE_KEY, se usa Supabase (Postgres en la nube).

Crear las tablas en Supabase

En el SQL Editor de tu proyecto Supabase:

create table if not exists goals (
  id int primary key default 1,
  sport text,
  description text,
  target_date date,
  details jsonb,
  updated_at timestamptz default now()
);

create table if not exists training_plan (
  id int primary key default 1,
  plan jsonb,
  updated_at timestamptz default now()
);

create table if not exists journal (
  id bigserial primary key,
  ts timestamptz default now(),
  note text
);

create table if not exists strength_log (
  id bigserial primary key,
  date date,
  exercises jsonb,
  notes text,
  logged_at timestamptz default now()
);

En Project Settings → API → copia la Project URL y la clave anon/public.

Importar histórico de Strava

1. Strava → Configuración → Mi cuenta → "Descargar o eliminar tu cuenta"
2. Dentro del ZIP: activities.csv
3. Dile a Claude: "Importa mi CSV de Strava, está en /ruta/activities.csv"
4. Puedes re-importar: las actividades no se duplican

8. Notas y límites

• Librería no oficial: si Garmin cambia su API, puede dejar de funcionar hasta que se actualice garminconnect (pip install -U garminconnect).
• Sin push/webhooks: Claude tira de los datos cuando se lo pides; no hay notificación automática en tiempo real.
• Los datos de fuerza dependen de que tu reloj/app los registre con detalle.
• El motor de recomendación es un motor de reglas transparente, no un diagnóstico médico. Si hay dolor o enfermedad, eso pesa más que cualquier número.

Variables de entorno

Variable	Requerido	Descripción
GARMIN_EMAIL	Sí	Email de Garmin Connect
GARMIN_PASSWORD	Sí	Contraseña de Garmin Connect
SUPABASE_URL	No	URL del proyecto Supabase
SUPABASE_KEY	No	Clave anon/public de Supabase
MCP_HOST	No	Host del servidor HTTP (default: 0.0.0.0)
MCP_PORT	No	Puerto del servidor HTTP (default: 8080)