Garmin Coach
by jvsantana
README.md
# 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](https://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):
```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:
```powershell
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).
## Início rápido (resumo)
Já tem Git e uv? Feche o Claude Desktop (bandeja → Quit) antes de instalar.
```powershell
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](https://github.com/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`](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):
```json
"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](https://modelcontextprotocol.io) **somente leitura** sobre a
[Garmin Connect Personal API](https://github.com/garmin/connect-personal-api-python) 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):
```bash
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](https://docs.astral.sh/uv/).
```bash
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.
```json
{
"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)
```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
```bash
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](https://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):
```bash
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
```
4. 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`):
```json
"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](LICENSE). O servidor `garmin_mcp` do taxuspt, instalado separadamente pelo `setup`, tem licença própria (MIT).