Skip to main content
Glama
Garmin Coach
by jvsantana

Garmin Coach MCP

Passo a passo do zero

1. O que você precisa ter

Item

Para quê

Conta no Garmin Connect com o relógio sincronizando

origem dos dados de saúde e treino

Conta no Intervals.icu ligada ao Garmin (Settings → Connections, com Upload planned workouts ativado)

cria os treinos e os envia ao relógio

Claude Desktop e/ou ChatGPT Desktop (use o Codex dele)

onde você conversa com o coach

Git

o uv baixa o pacote direto do GitHub

uv

instala o pacote e o Python 3.12 sozinho; você não precisa instalar Python

2. Instalar Git e uv

Windows (PowerShell):

winget install --id Git.Git -e
winget install --id astral-sh.uv -e

Alternativa para o uv, sem winget: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS: brew install git uv (ou curl -LsSf https://astral.sh/uv/install.sh | sh). Linux: curl -LsSf https://astral.sh/uv/install.sh | sh e o Git pelo gerenciador de pacotes da distribuição.

Depois feche e abra o terminal e confira:

git --version
uv --version

Se uv ou, mais adiante, garmin-coach não forem encontrados, rode uv tool update-shell e abra um novo terminal.

3. Instalar o coach

Feche o Claude Desktop e o ChatGPT Desktop pela bandeja (ícone → Quit); aberto, o Windows trava a atualização com "Acesso negado". Depois:

uv tool install --force git+https://github.com/jvsantana/garmin-coach-mcp
garmin-coach setup

Na primeira vez o uv baixa o Python e as dependências; pode levar alguns minutos.

4. Ter as informações à mão

O setup pergunta, no próprio terminal (nada disso passa pelo chat):

  • e-mail e senha do Garmin Connect e o código de verificação (MFA), se você usar;

  • a chave de API do Intervals.icu (Settings → Developer Settings → API Key);

  • seu fuso horário (ex.: America/Sao_Paulo) e em qual app configurar (Claude, ChatGPT ou os dois).

5. Conferir e usar

garmin-coach doctor

Abra o app de novo: no Claude Desktop, confira os servidores garmin e garmin-workouts em Configurações → Desenvolvedor; no ChatGPT Desktop, em Settings → MCP servers, usando uma sessão do Codex. Por fim, rode garmin-coach prompt --copy e cole o texto nas instruções de um Projeto (Claude) ou da sessão; o coach começa pela anamnese.

Para atualizar no futuro: feche os apps e repita o passo 3 (o setup mantém o que já existe).

Related MCP server: garmin-mcp

Início rápido (resumo)

Já tem Git e uv? Feche o Claude Desktop (bandeja → Quit) antes de instalar.

uv tool install --force git+https://github.com/jvsantana/garmin-coach-mcp
garmin-coach setup

(Em um clone local: uv tool install . --force. Se o repositório for privado, o git precisa estar autenticado.)

O garmin-coach setup:

  1. instala o servidor do taxuspt em ambiente próprio (ele exige mcp<2, este pacote exige mcp>=2, por isso não dá para ser dependência direta);

  2. faz o login do Garmin no terminal (e-mail, senha e MFA nunca passam pelo chat);

  3. pede a chave do Intervals.icu (Settings → Developer Settings → API Key), salva em arquivo e testa;

  4. grava a configuração no Claude Desktop (claude_desktop_config.json) e/ou no ChatGPT Desktop/Codex (~/.codex/config.toml, compartilhado com Codex CLI), com backup e sem apagar o que já existe.

Outros comandos: garmin-coach doctor (verifica tudo), garmin-coach config --format json|toml (só imprime a configuração), garmin-coach prompt --copy (copia o prompt do coach para colar no Projeto).

ChatGPT Desktop: os servidores locais funcionam no lado Codex do app (Settings → MCP servers), não nos chats comuns do ChatGPT. Abra uma sessão do Codex e peça ali. ChatGPT na web, chats comuns e claude.ai só aceitam servidores remotos (HTTPS público); veja a seção de modo HTTP.

Atualização: para a leitura de dados, o coach passou a usar o servidor taxuspt/garmin_mcp, que cobre bem mais dados que a Personal API oficial. O garmin-coach-mcp deste repositório fica como alternativa oficial e somente leitura; o intervals-workouts-mcp continua sendo quem cria treinos, perfil e plano.

Este repositório tem dois servidores MCP que trabalham juntos para o Claude atuar como coach:

Servidor

Comando

Função

garmin-coach

garmin-coach-mcp

Lê seus dados do Garmin Connect (somente leitura)

garmin-workouts

intervals-workouts-mcp

Cria treinos estruturados no Intervals.icu (que os envia ao Garmin), guarda o perfil do atleta e o plano de treino

O prompt do coach, que orquestra os dois (incluindo a anamnese inicial), está em COACH_PROMPT.md. A seção MCP de treinos deste README descreve o segundo servidor.

Configuração recomendada do garmin (taxuspt) para o coach

Só leitura e apenas o que o coach usa (o Intervals.icu cria os treinos):

"garmin": {
  "command": "uvx",
  "args": ["--python", "3.12", "--from", "git+https://github.com/Taxuspt/garmin_mcp", "garmin-mcp"],
  "env": {
    "GARMIN_TOOL_PROFILE": "minimal,health,training,activities",
    "GARMIN_DISABLED_TOOLS": "delete_activity,set_activity_exercise_sets,add_weigh_in,add_weigh_in_with_timestamps,delete_weigh_ins,add_body_composition,add_hydration_data,set_blood_pressure,set_fit_download_dir,download_activity_file,add_gear_to_activity,remove_gear_from_activity,create_manual_activity,set_activity_description,set_activity_event_type,set_activity_feel,set_activity_name,set_activity_type,set_perceived_effort,upload_course,delete_course,get_pregnancy_summary,get_menstrual_calendar_data,get_menstrual_data_for_date"
  }
}

Depois de reiniciar, confira a lista de ferramentas no Claude e desative qualquer outra de escrita que apareça.


MCP de leitura (garmin-coach)

Servidor MCP somente leitura sobre a Garmin Connect Personal API oficial. Ele deixa o Claude consultar seus treinos, sono, VFC, Body Battery, estresse, peso etc., para atuar como coach.

  • Dois modos, um código: stdio (local, Claude Desktop) e http (hospedado, com OAuth 2.1).

  • Somente leitura: a API pessoal da Garmin só permite GET; nenhuma ferramenta altera dados.

  • Uso pessoal: a Personal API é para os seus dados. Não use para atender vários usuários.

Segurança em resumo

Tema

Como é tratado

Chave da Garmin

Só por variável de ambiente ou arquivo (*_FILE), nunca por argumento de linha de comando

Acesso remoto

OAuth 2.1 + PKCE, registro dinâmico de cliente, login com senha única (GARMIN_MCP_ADMIN_PASSWORD)

Tokens em disco

Apenas hashes SHA-256; arquivo com permissão 0600; refresh token rotacionado

Força bruta

5 senhas erradas em 15 min bloqueiam o login (comparação em tempo constante)

Rede

Proteção contra DNS rebinding (host público + loopback); tokens vinculados ao recurso (RFC 8707)

Contêiner

Usuário não-root, volume /data, healthcheck

1. Gerar e guardar a chave

  1. No Garmin Connect, abra as configurações da API pessoal e gere uma chave.

  2. Guarde-a num arquivo só seu (não cole em chats nem versione):

mkdir -p ~/.config/garmin && umask 077
read -rs -p "Cole a chave e tecle Enter: " K && printf '%s' "$K" > ~/.config/garmin/connect-personal-api-key; unset K
chmod 600 ~/.config/garmin/connect-personal-api-key

2. Teste local (Claude Desktop, modo stdio)

Requer Python 3.12+ e uv.

uv tool install .            # instala o comando em ~/.local/bin/garmin-coach-mcp
export GARMIN_PERSONAL_API_KEY_FILE=~/.config/garmin/connect-personal-api-key
garmin-coach-mcp check       # valida a chave e a conexão com a Garmin

Adicione ao claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) e reinicie o Claude Desktop. O bloco env é obrigatório: o Claude Desktop não repassa o seu ambiente ao servidor.

{
  "mcpServers": {
    "garmin-coach": {
      "command": "/Users/VOCE/.local/bin/garmin-coach-mcp",
      "args": ["stdio"],
      "env": {
        "GARMIN_PERSONAL_API_KEY_FILE": "/Users/VOCE/.config/garmin/connect-personal-api-key",
        "GARMIN_MCP_DATA_DIR": "/Users/VOCE/.local/share/garmin-coach-mcp",
        "TZ": "America/Sao_Paulo"
      }
    }
  }
}

Depois peça, por exemplo: "Use a prompt weekly_review" ou "Como foi meu sono e minha VFC nas últimas duas semanas comparado ao mês anterior?".

Windows (PowerShell)

# guardar a chave (não aparece na tela nem no histórico)
New-Item -ItemType Directory -Force "$HOME\.config\garmin" | Out-Null
$k = Read-Host "Cole a chave" -AsSecureString
[System.Net.NetworkCredential]::new("", $k).Password | Set-Content -NoNewline "$HOME\.config\garmin\connect-personal-api-key"

uv tool install .
$env:GARMIN_PERSONAL_API_KEY_FILE = "$HOME\.config\garmin\connect-personal-api-key"
garmin-coach-mcp check

No claude_desktop_config.json, use "command": "C:\\Users\\VOCE\\.local\\bin\\garmin-coach-mcp.exe" e caminhos com barras duplas nos valores de env.

3. Hospedar (Coolify) e conectar no Claude

  1. Crie o recurso a partir deste repositório (Dockerfile ou docker-compose.yml), porta 8000, domínio com HTTPS (ex.: https://garmin-mcp.seudominio.com).

  2. Variáveis de ambiente (veja .env.example; marque as duas primeiras como secret): GARMIN_PERSONAL_API_KEY, GARMIN_MCP_ADMIN_PASSWORD (16+ caracteres), GARMIN_MCP_PUBLIC_URL (exatamente a URL pública, sem barra final), TZ.

  3. Adicione um volume persistente em /data (guarda o estado OAuth e o cache do token). Sem ele, cada redeploy exige reconectar o Claude.

  4. No Claude: Configurações → Conectores → Adicionar conector personalizado, URL https://garmin-mcp.seudominio.com/mcp. Aparecerá a tela de login do servidor: informe a senha.

Para revogar o acesso do Claude, apague /data/oauth-store.json e reinicie. Para trocar a chave da Garmin, atualize a variável e reinicie.

Ferramentas

list_activities, get_activity, get_activity_workouts, get_daily_summaries, get_steps, get_stress, get_body_battery, get_wellness_activity_summaries, get_sleep, get_sleep_summaries, get_hrv, get_hrv_summaries, get_heart_rate, get_heart_rate_zones, get_spo2, get_weight, get_fitness_age, get_profile_settings, mais o prompt weekly_review.

Decisões de projeto: datas aceitam YYYY-MM-DD, today e yesterday (no seu fuso); intervalos têm teto (GARMIN_MCP_MAX_RANGE_DAYS); séries intradiárias vêm resumidas por padrão (include_series=true traz tudo); respostas acima de GARMIN_MCP_MAX_RESPONSE_CHARS viram um erro que orienta o modelo a reduzir o período. Ficaram de fora por privacidade/escopo: ciclo menstrual, registros de alimentação e hidratação, e download de arquivos FIT.

Limitações conhecidas

  • O formato exato das respostas da Garmin não foi verificado contra uma conta real durante o desenvolvimento (sem chave disponível). A redução de séries usa nomes de campos conhecidos e uma regra genérica; se algo vier grande demais ou resumido demais, ajuste KNOWN_SERIES_KEYS em shaping.py.

  • A biblioteca oficial da Garmin é nova (v1.0.0); fixe a versão em produção.

  • Modo HTTP em instância única: o estado OAuth fica em arquivo local.

Desenvolvimento

uv venv && uv pip install -e ".[dev]"
ruff check . && pytest

Os testes cobrem datas, configuração, redução de séries, renovação de token em 401, as ferramentas via cliente MCP em memória e o fluxo OAuth completo (registro, PKCE, refresh com rotação, revogação, persistência após reinício, bloqueio por tentativas e host inválido).


MCP de treinos (garmin-workouts)

A Garmin só entrega a API de treinos a parceiros empresariais aprovados, e bibliotecas não oficiais quebram sem aviso. Por isso o caminho suportado é: Claude → Intervals.icu (API oficial, com chave pessoal) → Garmin Connect → relógio. O servidor gera o texto de treino do Intervals.icu a partir de um modelo tipado (blocos, repetições, alvos de FC ou ritmo), envia, lê de volta e avisa se a duração interpretada não bate com a esperada.

Configuração única (no Intervals.icu e no Garmin)

  1. Crie conta no Intervals.icu e conecte o Garmin (Settings → Connections), ativando Upload planned workouts.

  2. Em Settings → Sport Settings → Run, defina ritmo de limiar, FC de limiar e FC máxima e confira as zonas. Sem o ritmo de limiar, alvos de ritmo chegam ao relógio como "sem alvo".

  3. Em Settings → Developer Settings, gere a chave de API e guarde-a num arquivo (como a da Garmin):

mkdir -p ~/.config/intervals && umask 077
read -rs -p "Cole a chave e tecle Enter: " K && printf '%s' "$K" > ~/.config/intervals/api-key; unset K
  1. Teste: INTERVALS_API_KEY_FILE=~/.config/intervals/api-key intervals-workouts-mcp check (instalado junto com o garmin-coach-mcp por uv tool install .).

Claude Desktop (stdio)

Adicione um segundo servidor em mcpServers (ao lado de garmin-coach):

"garmin-workouts": {
  "command": "C:\\Users\\VOCE\\.local\\bin\\intervals-workouts-mcp.exe",
  "args": ["stdio"],
  "env": {
    "INTERVALS_API_KEY_FILE": "C:\\Users\\VOCE\\.config\\intervals\\api-key",
    "WORKOUTS_MCP_DATA_DIR": "C:\\Users\\VOCE\\.local\\share\\intervals-workouts-mcp",
    "TZ": "America/Sao_Paulo"
  }
}

Ferramentas

Ferramenta

O que faz

get_athlete_profile / update_athlete_profile

Perfil do atleta (objetivos, disponibilidade, histórico, saúde, preferências, equipamentos, estilo de vida) e lista de perguntas que ainda faltam

get_training_plan / save_training_plan

Plano macro (substitui o anterior; guarda as últimas 20 revisões com a justificativa)

check_setup

Testa a conexão e aponta limiar de ritmo/FC ausentes

preview_workouts

Mostra o texto que seria enviado, sem chamar a API

create_workouts

Cria/atualiza treinos (upsert por external_id), reenvia ao Garmin e confere o resultado

list_planned_workouts

Lista os treinos criados pelo coach

delete_planned_workouts

Apaga treinos futuros do coach

Salvaguardas: só mexe em eventos cujo external_id começa com coach- (seus treinos manuais e de outros apps ficam intactos); não cria nem apaga datas passadas; recusa treinos que misturam alvo de FC e de ritmo; create_workouts apaga e recria um treino existente para o Intervals.icu reenviá-lo ao Garmin (editar não dispara novo envio).

Limites que valem conhecer

  • O Intervals.icu envia ao Garmin só os próximos ~7 dias de treinos, atualizados diariamente.

  • O arquivo de perfil/plano fica em WORKOUTS_MCP_DATA_DIR (JSON, permissão 0600) e contém dados de saúde: faça backup e não o versione.

  • A sintaxe de texto do Intervals.icu foi levantada de documentação e fóruns, sem conta real durante o desenvolvimento. Por isso create_workouts valida lendo de volta; faça um treino de teste no relógio.

  • Hospedagem: docker compose sobe os dois servidores (portas 8000 e 8001). No Coolify, publique cada um em seu domínio e conecte cada URL /mcp como conector separado.

Variáveis do MCP de treinos

INTERVALS_API_KEY (ou _FILE), INTERVALS_ATHLETE_ID (padrão 0), WORKOUTS_MCP_DATA_DIR, WORKOUTS_MCP_TIMEZONE/TZ; modo HTTP: WORKOUTS_MCP_PUBLIC_URL, WORKOUTS_MCP_ADMIN_PASSWORD (16+ caracteres), WORKOUTS_MCP_PORT (8001).

Licença

MIT. O servidor garmin_mcp do taxuspt, instalado separadamente pelo setup, tem licença própria (MIT).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      A local MCP server that exposes Garmin Connect activity, health, and training data as tools for Claude Desktop. It provides read-only access to metrics like activities, sleep, heart rate, and training readiness.
      25
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A read-only remote MCP server that lets Claude query your own Garmin Connect wellness and activity data — sleep, HRV, Body Battery, stress, heart rate, daily summaries, and workout details — through Garmin's official Personal API, with OAuth sign-in so it works from mobile and desktop clients.
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A read-only remote MCP server that lets Claude query your own Garmin Connect data — sleep, HRV, Body Battery, stress, heart rate and activities — through Garmin's official Personal API, with OAuth sign-in so it works in the mobile app as well as on desktop.
      1,323 npm
      MIT