Garmin Coach
Read-only access to a user's Garmin Connect data (activities, workouts, sleep, HRV, Body Battery, stress, weight and other health/training metrics) through the official Garmin Connect Personal API, exposed in both local stdio and hosted HTTP (OAuth 2.1) modes, enabling an AI coach to review and analyze the athlete's training and recovery history. Structured workouts created in Intervals.icu are sent to the Garmin watch.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 | 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 -eAlternativa 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 --versionSe 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 setupNa 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 doctorAbra 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:
instala o servidor do taxuspt em ambiente próprio (ele exige
mcp<2, este pacote exigemcp>=2, por isso não dá para ser dependência direta);faz o login do Garmin no terminal (e-mail, senha e MFA nunca passam pelo chat);
pede a chave do Intervals.icu (Settings → Developer Settings → API Key), salva em arquivo e testa;
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-mcpdeste repositório fica como alternativa oficial e somente leitura; ointervals-workouts-mcpcontinua 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 |
|
| Lê seus dados do Garmin Connect (somente leitura) |
|
| 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) ehttp(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 ( |
Acesso remoto | OAuth 2.1 + PKCE, registro dinâmico de cliente, login com senha única ( |
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 |
1. Gerar e guardar a chave
No Garmin Connect, abra as configurações da API pessoal e gere uma chave.
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-key2. 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 GarminAdicione 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 checkNo 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
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).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.Adicione um volume persistente em
/data(guarda o estado OAuth e o cache do token). Sem ele, cada redeploy exige reconectar o Claude.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_KEYSemshaping.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 . && pytestOs 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)
Crie conta no Intervals.icu e conecte o Garmin (Settings → Connections), ativando Upload planned workouts.
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".
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 KTeste:
INTERVALS_API_KEY_FILE=~/.config/intervals/api-key intervals-workouts-mcp check(instalado junto com ogarmin-coach-mcpporuv 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 |
| Perfil do atleta (objetivos, disponibilidade, histórico, saúde, preferências, equipamentos, estilo de vida) e lista de perguntas que ainda faltam |
| Plano macro (substitui o anterior; guarda as últimas 20 revisões com a justificativa) |
| Testa a conexão e aponta limiar de ritmo/FC ausentes |
| Mostra o texto que seria enviado, sem chamar a API |
| Cria/atualiza treinos (upsert por |
| Lista os treinos criados pelo coach |
| 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_workoutsvalida lendo de volta; faça um treino de teste no relógio.Hospedagem:
docker composesobe os dois servidores (portas 8000 e 8001). No Coolify, publique cada um em seu domínio e conecte cada URL/mcpcomo 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
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
Garmin data in Claude: 135 tools — activities, sleep, HRV, training, workouts. Free, open source.
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Related MCP Servers
- AlicenseAqualityDmaintenanceA read-only MCP server that gives Claude Desktop access to your Garmin Connect data — daily health metrics, sleep, activities, training status, and body composition.6MIT
- FlicenseAqualityCmaintenanceA 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-
- AlicenseNot gradedqualityNot gradedmaintenanceA 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
- AlicenseNot gradedqualityNot gradedmaintenanceA 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 npmMIT