TrainBud

TrainBud

Fale com seus dados de treino.

TrainBud é um servidor MCP de código aberto que conecta seus dados de fitness do Garmin Connect ao Claude, Cursor e outros assistentes de IA. Pergunte sobre treinos, sono, frequência cardíaca, recuperação e composição corporal em linguagem simples — de forma privada, na sua máquina.

Aviso: TrainBud é um projeto comunitário não oficial. Não é afiliado, endossado ou patrocinado pela Garmin Ltd. Garmin Connect é uma marca registrada da Garmin Ltd.

Experimente

Depois de conectar ao seu cliente MCP, faça perguntas como:

• "O que eu fiz hoje?"
• "Como está meu sono esta semana?"
• "Estou recuperado o suficiente para treinar pesado amanhã?"
• "Minha frequência cardíaca em repouso está em tendência de queda?"

Veja examples/prompts.md para mais ideias.

Por que TrainBud

• Privado — as credenciais ficam no seu .env local; os dados são armazenados em cache na sua máquina
• Local-first — cache SQLite, tokens de sessão em .trainbud/
• Funciona em qualquer lugar — Windows, macOS, Linux (Node.js 20+)
• Qualquer cliente MCP — Claude Desktop, Cursor e outros clientes compatíveis com stdio
• Busca inteligente — chamadas de API em lote e reautenticação automática quando as sessões expiram

Início rápido

npx trainbud setup

O assistente de configuração orienta você pelas credenciais, autenticação e conexão com o Cursor ou Claude Desktop — sem necessidade de editar a configuração do MCP. Depois, reinicie seu cliente MCP e pergunte o que você fez hoje.

Para manter trainbud no seu PATH em vez de digitar npx toda vez:

npm install -g trainbud
trainbud setup

Requer Node 22+. Guia completo: 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 do Claude Code (recomendado)

Instale como um plugin do Claude Code — skills e servidor MCP em um único passo:

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

Defina as credenciais e reinicie o Claude Code:

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

Os arquivos do plugin ficam em plugin/. Veja plugin/README.md.

Skills do Claude Code (no repositório)

Este repositório também inclui skills de projeto em .claude/skills/ para desenvolvimento sem instalar o plugin:

Abra o repositório no Claude Code (claude neste diretório) — as skills carregam automaticamente.

Para usar as skills em todos os projetos sem o plugin, copie-as para ~/.claude/skills/.

Após a configuração, reinicie seu cliente MCP e tente /trainbud com "O que eu fiz hoje?"

Painel

trainbud serve hospeda um painel em /dashboard. Ele é otimizado para celular, porque o fluxo de pareamento é: você está ao lado do relógio segurando um celular quando aprova um código.

Ele mostra o que se destaca hoje em relação às suas próprias linhas de base, esta semana em relação à semana passada, e a frequência cardíaca em repouso e o sono plotados em relação à sua própria mediana de 30 dias — tudo lido do armazenamento local de histórico, então renderiza instantaneamente e funciona mesmo quando sua sessão do Connect expirou. Uma quebra na linha é um dia sem medição, não um zero.

É também onde você diz ao TrainBud com quem ele está falando:

Uso. O TrainBud roda com sua própria chave de provedor de IA, então cada pergunta e cada insight diário é cobrado de você. O painel mostra os tokens e o custo por chamada, o acumulado do mês e um gráfico de 30 dias. Um modelo sem preço publicado nesta versão é registrado com seu custo marcado como desconhecido em vez de zero — uma chamada com preço zero tornaria um limite que nunca pode ser acionado.

Nada nesta página sai da sua máquina. Não há endpoint para onde enviar.

Widget para relógio Garmin (Connect IQ)

Veja recuperação, sono, atividade, estresse e VO2 máx. no seu relógio Garmin por meio de um widget Connect IQ em ciq/.

Requer: trainbud serve em execução + túnel HTTPS (mesma configuração da IA web).

1. Inicie o servidor e o túnel:

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

2. Compile e carregue o widget — veja ciq/README.md
3. No Garmin Connect Mobile → Connect IQ → configurações do TrainBud, defina:
   • URL do servidor — a URL do seu túnel (ex.: https://abc.trycloudflare.com)
4. Abra o widget no seu relógio — ele mostra um código de pareamento. Aprove-o no painel (/dashboard?token=YOUR_API_KEY) para concluir a configuração. O painel troca esse token por um cookie de sessão e o remove da URL, então a barra de endereço fica segura para capturas de tela depois.

A visão geral mostra recuperação e sono do último resumo em cache, então renderiza sem esperar pela rede. Abra-o e toque ou deslize para percorrer os cartões que você deixou ativados no painel. O relógio chama GET /api/watch — um resumo JSON compacto, não o protocolo MCP completo.

Conectar ao Claude Desktop

Edite 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"
      }
    }
  }
}

Com trainbud no seu PATH (npm install -g trainbud, ou npm link de um clone), aponte o cliente para o comando em vez de um caminho:

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

Reinicie seu cliente MCP e comece a fazer perguntas.

Ferramentas

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 um desses também funciona como npx trainbud <command> sem instalar nada.

Solução de problemas: trainbud: command not found

Use npx trainbud <command> ou instale-o globalmente com npm install -g trainbud. Executando a partir de um clone? Execute npm link uma vez na raiz do repositório, ou chame o ponto de entrada compilado diretamente com node dist/index.js doctor (após npm run build).

Configuração

Segurança e privacidade

• As credenciais ficam apenas no seu arquivo .env local — nunca enviadas a terceiros
• Tokens de sessão em .trainbud/session.json são tão sensíveis quanto uma senha
• Erros de ferramentas são sanitizados antes de chegar ao cliente de IA
• Usa o pacote npm não oficial garmin-connect (não a API OAuth empresarial da Garmin)
• MFA não é suportado pela biblioteca subjacente — desative a MFA ou use uma senha específica do aplicativo
• O servidor vincula 127.0.0.1 por padrão. Ele só é acessível pela internet se você apontar um túnel para ele, e toda rota exceto /health precisa da chave da API
• O painel recebe a chave uma vez, em /dashboard?token=…, e depois a troca por um cookie de sessão HttpOnly e redireciona para uma URL limpa — então a chave não fica na sua barra de endereço, no seu histórico ou em uma captura de tela
• Um relógio pareado mantém um token com escopo para esse relógio, criado no pareamento e armazenado no servidor como um hash SHA-256. trainbud devices os lista, trainbud devices revoke <id> takes one away — without logging out the dashboard, /mcp, ou seus outros relógios. Um relógio pareado antes da versão 0.5.2 mantém a própria chave da API; repare-o para trocá-la por um token com escopo
• Cada resposta carrega Content-Security-Policy, X-Content-Type-Options, X-Frame-Options e Referrer-Policy, incluindo os 401. HSTS é enviado apenas em uma solicitação que realmente chegou via TLS, então o painel de loopback permanece acessível

O que o TrainBud não é

• Não é um serviço hospedado. Não há conta TrainBud e nenhum servidor TrainBud. Você o executa na sua máquina, com suas próprias credenciais Garmin
• Não é uma integração oficial da Garmin. Ele usa uma biblioteca não oficial contra a API web do Connect. A Garmin pode alterar essa API sem aviso, e altera
• Não é compatível com MFA. Se sua conta do Connect tiver MFA ativada, não será possível fazer login
• Não é gratuito para perguntar. Os recursos de IA usam sua própria chave Anthropic e são cobrados de você. O painel mede cada chamada e pode recusar além de um limite que você definir

Solução de problemas

Desenvolvimento

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

Use .nvmrc com nvm/fnm para Node 22. npm run test:coverage relata cobertura pelo próprio executor de testes do Node, e npm run test:watch reexecuta em mudanças. Consulte CONTRIBUTING.md e docs/VAULT.md para notas de arquitetura e design (vault Obsidian, fora deste repositório).

Roadmap

• Tendências de VO2 máx
• Níveis de estresse
• Insights de treino
• Comparação de treinos
• Imagem Docker

Licença

MIT — veja LICENSE.

Garmin Connect é uma marca registrada da Garmin Ltd. Este projeto não é afiliado à Garmin Ltd.