TrainBud

TrainBud

Habla con tus datos de entrenamiento.

TrainBud es un servidor MCP de código abierto que conecta tus datos de fitness de Garmin Connect con Claude, Cursor y otros asistentes de IA. Pregunta sobre entrenamientos, sueño, frecuencia cardíaca, recuperación y composición corporal en lenguaje natural — de forma privada, en tu máquina.

Aviso: TrainBud es un proyecto comunitario no oficial. No está afiliado, respaldado ni patrocinado por Garmin Ltd. Garmin Connect es una marca comercial de Garmin Ltd.

Pruébalo

Una vez conectado a tu cliente MCP, haz preguntas como:

• "¿Qué hice hoy?"
• "¿Cómo ha sido mi sueño esta semana?"
• "¿Estoy lo suficientemente recuperado para entrenar fuerte mañana?"
• "¿Mi frecuencia cardíaca en reposo está bajando?"

Consulta examples/prompts.md para más ideas.

Por qué TrainBud

• Privado — las credenciales permanecen en tu .env local; los datos se almacenan en caché en tu máquina
• Local primero — caché SQLite, tokens de sesión en .trainbud/
• Funciona en todas partes — Windows, macOS, Linux (Node.js 20+)
• Cualquier cliente MCP — Claude Desktop, Cursor y otros clientes compatibles con stdio
• Obtención inteligente — llamadas API por lotes y re-autenticación automática cuando las sesiones expiran

Inicio rápido

npx trainbud setup

El asistente de configuración te guía a través de las credenciales, la autenticación y la conexión de Cursor o Claude Desktop — sin necesidad de editar la configuración de MCP. Luego reinicia tu cliente MCP y pregúntale qué hiciste hoy.

Para mantener trainbud en tu PATH en lugar de escribir npx cada vez:

npm install -g trainbud
trainbud setup

Requiere Node 22+. Guía completa: QUICKSTART.md

git clone https://github.com/Zsadigzade/trainbud.git
cd trainbud
npm install
npm run build
npm link          # puts `trainbud` on your PATH; undo with `npm unlink -g trainbud`
trainbud setup

Plugin de Claude Code (recomendado)

Instálalo como un plugin de Claude Code — habilidades y servidor MCP en un solo paso:

/plugin marketplace add Zsadigzade/trainbud
/plugin install trainbud@trainbud

Configura las credenciales y luego reinicia Claude Code:

export GARMIN_EMAIL="your@email.com"
export GARMIN_PASSWORD="yourpassword"

Los archivos del plugin están en plugin/. Consulta plugin/README.md.

Habilidades de Claude Code (en el repositorio)

Este repositorio también incluye habilidades de proyecto en .claude/skills/ para desarrollo sin instalar el plugin:

Abre el repositorio en Claude Code (claude en este directorio) — las habilidades se cargan automáticamente.

Para usar las habilidades en cualquier proyecto sin el plugin, cópialas a ~/.claude/skills/.

Después de la configuración, reinicia tu cliente MCP y prueba /trainbud con "¿Qué hice hoy?"

Panel de control

trainbud serve aloja un panel de control en /dashboard. Está diseñado primero para teléfonos, porque el flujo de emparejamiento es: estás junto al reloj sosteniendo un teléfono cuando apruebas un código.

Muestra lo que destaca hoy en comparación con tus propios valores de referencia, esta semana frente a la anterior, y la frecuencia cardíaca en reposo y el sueño trazados frente a tu propia mediana de 30 días — todo leído desde el almacén de historial local, por lo que se muestra al instante y funciona incluso cuando tu sesión de Connect ha expirado. Una interrupción en una línea es un día sin medición, no un cero.

También es donde le dices a TrainBud con quién está hablando:

Uso. TrainBud funciona con tu propia clave de proveedor de IA, por lo que cada pregunta y cada información diaria se te cobra a ti. El panel de control muestra los tokens y el costo por llamada, el mes hasta la fecha y un gráfico de 30 días. Un modelo para el que esta compilación no tiene un precio publicado se registra con su costo marcado como desconocido en lugar de cero — una llamada con precio cero haría que un límite que nunca puede activarse.

Nada en esta página sale de tu máquina. No hay ningún endpoint al que enviarlo.

Widget para reloj Garmin (Connect IQ)

Consulta recuperación, sueño, actividad, estrés y VO2 máx. en tu reloj Garmin mediante un widget Connect IQ en ciq/.

Requiere: trainbud serve en ejecución + túnel HTTPS (misma configuración que la IA web).

1. Inicia el servidor y el túnel:

   trainbud serve
   cloudflared tunnel --url http://127.0.0.1:3847
   

2. Compila y carga el widget — consulta ciq/README.md
3. En Garmin Connect Mobile → Connect IQ → configuración de TrainBud, establece:
   • URL del servidor — tu URL de túnel (p. ej., https://abc.trycloudflare.com)
4. Abre el widget en tu reloj — muestra un código de emparejamiento. Apruébalo en el panel de control (/dashboard?token=YOUR_API_KEY) para completar la configuración. El panel de control intercambia ese token por una cookie de sesión y lo elimina de la URL, por lo que la barra de direcciones es segura para capturas de pantalla después.

La vista rápida muestra recuperación y sueño del último resumen en caché, por lo que se renderiza sin esperar la red. Ábrelo y toca o desliza para recorrer las tarjetas que dejaste activadas en el panel de control. El reloj llama a GET /api/watch — un resumen JSON compacto, no el protocolo MCP completo.

Conectar a Claude Desktop

Edita claude_desktop_config.json:

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

{
  "mcpServers": {
    "trainbud": {
      "command": "node",
      "args": ["C:/path/to/trainbud/dist/index.js", "start"],
      "env": {
        "GARMIN_EMAIL": "your@email.com",
        "GARMIN_PASSWORD": "yourpassword"
      }
    }
  }
}

Con trainbud en tu PATH (npm install -g trainbud, o npm link desde un clon), apunta el cliente al comando en lugar de a una ruta:

{
  "mcpServers": {
    "trainbud": {
      "command": "trainbud",
      "args": ["start"]
    }
  }
}

Reinicia tu cliente MCP y comienza a hacer preguntas.

Herramientas

CLI

trainbud setup          # Interactive first-time setup (recommended)
trainbud serve          # Remote HTTP MCP for web AI (claude.ai, ChatGPT)
trainbud check          # Live diagnostics against all tools
trainbud doctor         # What the watch would see: public URL, AI key, history depth
trainbud backfill       # Pull Garmin history into the local store (resumable)
trainbud findings       # What stands out against your own baselines
trainbud start          # Start the MCP server (stdio)
trainbud auth           # Force re-authentication
trainbud cache clear    # Clear cached data
trainbud devices        # List paired watches
trainbud devices revoke <id>   # Take one watch's access away
trainbud status         # Show session and cache status
trainbud --version      # Print version

Cada uno de estos también funciona como npx trainbud <command> sin instalar nada.

Solución de problemas: trainbud: command not found

Usa npx trainbud <command>, o instálalo globalmente con npm install -g trainbud. ¿Ejecutando desde un clon? Ejecuta npm link una vez desde la raíz del repositorio, o llama al punto de entrada compilado directamente con node dist/index.js doctor (después de npm run build).

Configuración

Seguridad y privacidad

• Las credenciales viven solo en tu archivo .env local — nunca se envían a un tercero
• Los tokens de sesión en .trainbud/session.json son tan sensibles como una contraseña
• Los errores de herramientas se sanitizan antes de llegar al cliente de IA
• Usa el paquete npm no oficial garmin-connect (no la API OAuth empresarial de Garmin)
• MFA no es compatible con la biblioteca subyacente — desactiva MFA o usa una contraseña específica de aplicación
• El servidor se enlaza a 127.0.0.1 por defecto. Solo es accesible desde internet si apuntas un túnel hacia él, y cada ruta excepto /health necesita la clave API
• El panel de control toma la clave una vez, en /dashboard?token=…, luego la intercambia por una cookie de sesión HttpOnly y redirige a una URL limpia — para que la clave no quede en tu barra de direcciones, tu historial o una captura de pantalla
• Un reloj emparejado tiene un token limitado a ese reloj, creado en el emparejamiento y almacenado en el servidor como un hash SHA-256. trainbud devices los lista, trainbud devices revoke <id> takes one away — without logging out the dashboard, /mcp, o tus otros relojes. Un reloj emparejado antes de 0.5.2 tiene la clave API en sí; vuelve a emparejarlo para intercambiarla por un token limitado
• Cada respuesta lleva Content-Security-Policy, X-Content-Type-Options, X-Frame-Options y Referrer-Policy, incluidos los 401. HSTS se envía solo en una solicitud que realmente llegó a través de TLS, para que el panel de control de bucle local siga siendo accesible

Lo que TrainBud no es

• No es un servicio alojado. No hay cuenta de TrainBud ni servidor de TrainBud. Tú lo ejecutas, en tu máquina, con tus propias credenciales de Garmin
• No es una integración oficial de Garmin. Impulsa una biblioteca no oficial contra la API web de Connect. Garmin puede cambiar esa API sin previo aviso, y lo hace
• No es compatible con MFA. Si tu cuenta de Connect tiene MFA activado, esto no iniciará sesión
• No es gratis para preguntar. Las funciones de IA funcionan con tu propia clave de Anthropic y se te facturan. El panel de control mide cada llamada y puede rechazar más allá de un límite que establezcas

Solución de problemas

Desarrollo

npm install
npm run build
npm test          # 573 tests via the Node test runner
npm run lint
npm run dev       # Start with auto-reload

Usa .nvmrc con nvm/fnm para Node 22. npm run test:coverage informa la cobertura a través del propio ejecutor de pruebas de Node, y npm run test:watch se vuelve a ejecutar al detectar cambios. Consulta CONTRIBUTING.md y docs/VAULT.md para notas de arquitectura y diseño (bóveda de Obsidian, fuera de este repositorio).

Hoja de ruta

• Tendencias de VO2 máx
• Niveles de estrés
• Información sobre entrenamiento
• Comparación de entrenamientos
• Imagen de Docker

Licencia

MIT — consulta LICENSE.

Garmin Connect es una marca comercial de Garmin Ltd. Este proyecto no está afiliado con Garmin Ltd.