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

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

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