Garmin MCP Server

Conecta-se ao Garmin Connect para expor seus dados de fitness e saúde a clientes compatíveis com MCP.

Documentação

Garmin MCP Server

Este servidor Model Context Protocol (MCP) conecta-se ao Garmin Connect e expõe seus dados de condicionamento físico e saúde para o Claude e outros clientes compatíveis com MCP.

A API do Garmin é acessada por meio da incrível biblioteca python-garminconnect.

Recursos

Listar atividades recentes com suporte a paginação
Obter informações detalhadas de atividades
Editar atividades: nome, tipo, descrição/anotações, tipo de evento, esforço percebido (RPE) e sensação
Acessar métricas de saúde (passos, frequência cardíaca, sono, estresse, respiração)
Visualizar dados de composição corporal
Acompanhar status de treinamento e prontidão
Acessar FTP de ciclismo e métricas de limiar de lactato
Gerenciar equipamentos e acessórios
Acessar treinos e planos de treinamento
Inspecionar estruturas detalhadas de etapas de treino, incluindo grupos de repetição e metas de ritmo de natação
Agregados semanais de saúde (passos, estresse, minutos de intensidade)
Análises avançadas de ciclismo: zonas de potência, análise de arquivos FIT, inteligência de troca eletrônica DI2
Tendência de carga de treinamento (CTL/ATL/TSB), tendência de VFC, tendência de VO2 máx, tendência de frequência respiratória
Curva de Duração de Potência, detecção de subidas com VAM, deriva cardíaca (desacoplamento aeróbico), cálculos de W/kg

Cobertura de Ferramentas

Este servidor MCP implementa mais de 110 ferramentas cobrindo ~90% da biblioteca python-garminconnect (v0.3.2):

✅ Gerenciamento de Atividades (20 ferramentas) - inclui ferramentas de escrita para tipo, descrição, tipo de evento, esforço percebido e sensação
✅ Saúde e Bem-estar (31 ferramentas) - inclui ferramentas personalizadas de resumo leve
✅ Treinamento e Desempenho (13 ferramentas) - inclui tendências de CTL/ATL/TSB, VFC, VO2 máx e respiração
✅ Treinos (8 ferramentas)
✅ Dispositivos (7 ferramentas)
✅ Gerenciamento de Equipamentos (5 ferramentas)
✅ Acompanhamento de Peso (5 ferramentas)
✅ Desafios e Medalhas (10 ferramentas)
✅ Nutrição (8 ferramentas) - registros alimentares, refeições, alimentos personalizados e registro de alimentos
✅ Saúde da Mulher (3 ferramentas)
✅ Perfil do Usuário (3 ferramentas)
✅ Construtores de Treinos de Alto Nível (4 ferramentas) - criar e agendar treinos sem escrever JSON
✅ Percursos (3 ferramentas) - listar / enviar GPX como percurso / excluir percurso
✅ Análise de Atividades (2 ferramentas) - análise de arquivos FIT, Curva de Duração de Potência; requer medidor de potência e/ou Di2
✅ Downloads de Arquivos de Atividade (2 ferramentas) - baixar arquivos de atividade em formato FIT, GPX, TCX ou CSV

Observação: As ferramentas de Análise de Atividades exigem um medidor de potência compatível (ex.: Garmin Rally, Favero Assioma, PowerTap P1) e/ou troca eletrônica Shimano Di2 / SRAM eTap. A dependência fitparse é instalada automaticamente.

Downloads de Arquivos de Atividade

Duas ferramentas permitem baixar um arquivo bruto de atividade para o disco:

download_activity_file(activity_id, format="fit", output_dir=None) — baixa a atividade e a salva no diretório configurado. format aceita fit (padrão), gpx, tcx ou csv.
set_fit_download_dir(path) — define e persiste o diretório de download padrão (gravado no arquivo de configuração).

Onde os arquivos são salvos (precedência):

Argumento output_dir — substituição pontual, não persistida.
Variável de ambiente GARMIN_FIT_DOWNLOAD_DIR.
Configuração persistida definida via set_fit_download_dir.

Comportamento na primeira execução: se nenhum diretório estiver configurado, download_activity_file retorna status: "needs_setup". O assistente perguntará onde você deseja salvar os arquivos (sugerindo o diretório atual como padrão), chamará set_fit_download_dir para persistir sua escolha e então tentará o download novamente automaticamente.

Endpoints Intencionalmente Ignorados

Alguns endpoints não são implementados devido a considerações de desempenho ou complexidade:

Alto Volume de Dados:

get_activity_details() - Retorna grandes trilhas GPS e dados de gráficos (50KB-500KB). Use get_activity() para resumos.

Formatos de Treino Especializados:

upload_running_workout(), upload_cycling_workout(), upload_swimming_workout() - Uploads de treinos específicos por esporte. Use upload_workout() para treinos gerais.

Operações de Manutenção e Destrutivas:

delete_activity(), delete_blood_pressure() - Operações destrutivas exigem consideração cuidadosa.
Métodos internos/autenticação: login(), resume_login(), connectapi(), download() - Tratados automaticamente pela biblioteca.

Se você precisar de algum desses endpoints, abra uma issue.

Filtragem de Ferramentas

Este servidor registra mais de 110 ferramentas por padrão, o que pode ser muito contexto para um LLM carregar em cada sessão. Você pode expor apenas as ferramentas que precisa com duas variáveis de ambiente opcionais:

Variável de ambiente	Efeito
`GARMIN_ENABLED_TOOLS`	Lista de permissões separada por vírgulas — se definida, apenas essas ferramentas são registradas.
`GARMIN_DISABLED_TOOLS`	Lista de bloqueios separada por vírgulas — as ferramentas listadas são ignoradas. Ignorada se uma lista de permissões estiver definida.

Os nomes das ferramentas não diferenciam maiúsculas de minúsculas. Com nenhuma variável definida, todas as ferramentas são registradas (comportamento padrão inalterado). Nomes que não correspondem a nenhuma ferramenta são ignorados com um aviso em stderr, o que facilita identificar erros de digitação.

Exemplo — exponha apenas sono, estresse e atividades recentes:

"env": {
  "GARMIN_ENABLED_TOOLS": "get_sleep_data,get_stress_summary,get_activities"
}

Ferramentas de treino de alto nível

Essas ferramentas construtoras permitem que um LLM crie e agende treinos sem escrever JSON bruto do Garmin.

`create_walk_run_workout`

Cria um treino intervalado de caminhada/corrida com alvo opcional de zona de frequência cardíaca.

{
  "name": "W3 Mié 2:2",
  "run_seconds": 120,
  "walk_seconds": 120,
  "repeats": 9,
  "warmup_min": 10,
  "cooldown_min": 8,
  "hr_zone": "Z3"
}

Retorna: {"status": "success", "workout_id": 1234567890, ...}

`create_z2_walk_workout`

Cria um treino estável de caminhada Z2.

{
  "name": "Z2 Walk 45m",
  "duration_min": 45,
  "hr_min": 110,
  "hr_max": 130
}

Retorna: {"status": "success", "workout_id": 1234567890, ...}

`create_strength_workout`

Cria um treino de força a partir de uma lista de exercícios. Cada um vira uma etapa baseada em repetições, com o nome mantido na descrição da etapa. O nome também é enviado como exerciseName, mas o Garmin só o retém quando corresponde a uma de suas próprias chaves de exercício (ex.: FARMERS_CARRY) — qualquer outro valor é aceito e depois armazenado vazio.

category é opcional e passado diretamente. Omita-o e a chave fica de fora do payload por completo, o que o Garmin aceita. Forneça-o e ele deve ser uma das categorias de exercício do Garmin — qualquer outra coisa, incluindo OTHER e UNASSIGNED, é rejeitada com 400 - Invalid category. A lista completa é publicada em Exercises.json.

{
  "name": "Full Body A",
  "exercises": [
    {"name": "Sentadillas", "sets": 3, "reps": 12, "rest_seconds": 90},
    {"name": "Flexiones",   "sets": 3, "reps": 15, "rest_seconds": 60},
    {"name": "Peso muerto", "sets": 3, "reps": 10, "rest_seconds": 90},
    {"name": "Farmers Carry 40m", "sets": 3, "reps": 1, "rest_seconds": 90, "category": "CARRY"}
  ]
}

Retorna: {"status": "success", "workout_id": 1234567890, ...}

`schedule_week`

Agenda vários treinos em uma única chamada.

{
  "week": [
    {"date": "2026-05-12", "workout_id": 1234567890},
    {"date": "2026-05-14", "workout_id": 1234567891}
  ]
}

Retorna: {"status": "complete", "scheduled": [...]}

Exemplo de fluxo completo

create_walk_run_workout(name="W3 Mié 2:2", run_seconds=120, walk_seconds=120,
                        repeats=9, warmup_min=10, cooldown_min=8)
  → workout_id = 1560092011

schedule_workout(workout_id=1560092011, date="2026-05-06")
  → OK

Após sincronizar o relógio, o treino aparece no calendário do Forerunner 965.

Condições de término brutas do `upload_workout`

Ao construir JSON de treino personalizado para upload_workout ou upload_workouts, o endCondition.conditionTypeId e o endCondition.conditionTypeKey devem corresponder ao mapeamento canônico do Garmin. O Garmin trata o conditionTypeId numérico como a fonte da verdade; se a chave e o ID entrarem em conflito, o Garmin armazena a condição que corresponde ao ID.

Por exemplo, isto é inválido para uma condição de término por frequência cardíaca porque o ID 4 é calories, não heart.rate:

{
  "endCondition": {
    "conditionTypeId": 4,
    "conditionTypeKey": "heart.rate"
  },
  "endConditionValue": 145
}

Use o ID 6 para frequência cardíaca:

{
  "endCondition": {
    "conditionTypeId": 6,
    "conditionTypeKey": "heart.rate"
  },
  "endConditionValue": 145
}

IDs comuns de condições de término:

ID	Chave
1	`lap.button`
2	`time`
3	`distance`
4	`calories`
5	`power`
6	`heart.rate`
7	`iterations`
8	`fixed.rest`
9	`fixed.repetition`
10	`reps`
11	`training.peaks.tss`

Tipos de alvo brutos do `upload_workout`

Ao construir JSON bruto de treino do Garmin, o targetType.workoutTargetTypeId e o targetType.workoutTargetTypeKey devem usar o mapeamento canônico do Garmin. O Garmin trata o ID numérico como autoritativo: um payload incompatível como {"workoutTargetTypeId": 6, "workoutTargetTypeKey": "heart.rate"} é armazenado como pace.zone, porque o ID 6 significa pace.zone.

Para uma faixa personalizada de frequência cardíaca, use o tipo de alvo ID 4 com heart.rate.zone e coloque a faixa de bpm em targetValueOne / targetValueTwo. Esses campos de valor pertencem à etapa do treino, junto com targetType; não os aninhe dentro do objeto targetType:

{
  "targetType": {
    "workoutTargetTypeId": 4,
    "workoutTargetTypeKey": "heart.rate.zone"
  },
  "targetValueOne": 143,
  "targetValueTwo": 157
}

O mesmo formato se aplica a uma faixa personalizada de ritmo de corrida. Os limites de ritmo usam metros por segundo:

{
  "targetType": {
    "workoutTargetTypeId": 6,
    "workoutTargetTypeKey": "pace.zone"
  },
  "targetValueOne": 1.9607843,
  "targetValueTwo": 2.0833333
}

Esse exemplo representa 8:00–8:30 min/km. O limite numérico inferior é listado primeiro para consistência com o exemplo de frequência cardíaca; o Garmin normaliza qualquer ordem de limites. O Garmin descarta silenciosamente valores aninhados dentro de targetType, deixando um alvo de ritmo sem faixa ativa. As ferramentas de upload corrigem esse erro de aninhamento inequívoco, mas rejeitam a solicitação se valores aninhados e de nível de etapa entrarem em conflito.

Para uma zona de FC nomeada do Garmin, use o mesmo tipo de alvo com zoneNumber:

{
  "targetType": {
    "workoutTargetTypeId": 4,
    "workoutTargetTypeKey": "heart.rate.zone"
  },
  "zoneNumber": 3
}

Use zoneNumber ou targetValueOne / targetValueTwo em um alvo, não ambos. O Garmin trata a zona nomeada como autoritativa e descarta silenciosamente uma faixa personalizada coexistente, então as ferramentas de upload rejeitam esse formato ambíguo.

Instalação com um clique (Claude Desktop)

A maneira mais fácil de adicionar este servidor ao Claude Desktop é por meio do arquivo de Extensão de Desktop .dxt — sem necessidade de editar JSON.

Baixar e instalar

Baixe o garmin-mcp.dxt mais recente da página de Releases.
Arraste o arquivo .dxt para a janela do Claude Desktop, ou clique duas vezes nele, ou vá em Configurações → Extensões → Instalar Extensão e selecione o arquivo.
O Claude Desktop solicitará configuração opcional (caminho do token, e-mail, senha).

Autenticação na primeira vez

A extensão instala e executa o servidor automaticamente, mas você precisa autenticar com o Garmin uma vez antes que os dados possam ser buscados:

uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth

Isso salva os tokens OAuth em ~/.garminconnect. Depois disso, o servidor funciona sem nenhuma credencial na configuração.

Observação: Os tokens são válidos por aproximadamente 6 meses. Execute garmin-mcp-auth novamente quando eles expirarem.

Crie o `.dxt` você mesmo

bash scripts/build_dxt.sh   # produces garmin-mcp.dxt in the repo root

Configuração

Início Rápido para Clientes MCP

A maneira mais fácil de usar este servidor MCP com o Claude Desktop, Codex ou outro cliente MCP é autenticar uma vez antes de adicionar o servidor à sua configuração.

Pré-requisitos

Python 3.12+
Conta Garmin Connect
MFA pode ser necessário se estiver habilitado na sua conta

Etapa 1: Pré-autenticação (única vez)

Antes de adicionar o servidor ao seu cliente MCP, autentique uma vez no seu terminal:


# Install and run authentication tool
uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp-auth

# You'll be prompted for:
# - Email (or set GARMIN_EMAIL env var)
# - Password (or set GARMIN_PASSWORD env var)
# - MFA code (if enabled on your account)

# OAuth tokens will be saved to ~/.garminconnect

Você pode verificar suas credenciais a qualquer momento com

uv run garmin-mcp-auth --verify

Observação: Você também pode definir credenciais por meio de variáveis de ambiente:

GARMIN_EMAIL=your@email.com GARMIN_PASSWORD=secret garmin-mcp-auth

Se você não tiver o MFA habilitado, também pode pular garmin-mcp-auth e passar GARMIN_EMAIL e GARMIN_PASSWORD como variáveis de ambiente diretamente para o seu cliente MCP, se suportado. Para melhor segurança, prefira o fluxo de pré-autenticação acima e mantenha as credenciais fora da configuração do cliente MCP.

Etapa 2: Configurar o Claude Desktop

Adicione às configurações MCP do seu Claude Desktop SEM credenciais:

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

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ]
    }
  }
}

Importante: Nenhum GARMIN_EMAIL ou GARMIN_PASSWORD necessário na configuração! O servidor usa seus tokens salvos.

Etapa 3: Reinicie seu cliente MCP

Seus dados do Garmin agora estão disponíveis para seu cliente MCP.

Para Codex e outros clientes, veja os exemplos abaixo.

Configuração de Desenvolvimento

Instale os pacotes necessários em um novo ambiente:

uv sync

Executando o Servidor

Configuração

Suas credenciais do Garmin Connect são lidas de variáveis de ambiente:

GARMIN_EMAIL: Seu endereço de e-mail do Garmin Connect
GARMIN_EMAIL_FILE: Caminho para um arquivo contendo seu endereço de e-mail do Garmin Connect
GARMIN_PASSWORD: Sua senha do Garmin Connect
GARMIN_PASSWORD_FILE: Caminho para um arquivo contendo sua senha do Garmin Connect
GARMIN_IS_CN: Defina como true para usar o Garmin Connect China (garmin.cn) em vez da versão internacional (padrão: false)
GARMIN_FIT_DOWNLOAD_DIR: Diretório padrão para arquivos de atividade baixados. Quando definido, pula o prompt de configuração da primeira execução em download_activity_file.
GARMIN_FIT_CONFIG: Caminho para o arquivo de configuração persistido do diretório de download (padrão: ~/.garminconnect_fit_config.json). Segredos baseados em arquivos são úteis em determinados ambientes, como dentro de um contêiner Docker. Observe que você não pode definir GARMIN_EMAIL e GARMIN_EMAIL_FILE ao mesmo tempo, da mesma forma que não pode definir GARMIN_PASSWORD e GARMIN_PASSWORD_FILE simultaneamente.

Transporte

Por padrão, o servidor se comunica via stdio, que é o que o Claude Desktop, o MCP Inspector e a maioria dos clientes locais esperam. Para servir via HTTP (por exemplo, ao executar em um contêiner ou Kubernetes), defina o transporte por meio de variáveis de ambiente:

GARMIN_MCP_TRANSPORT: stdio (padrão), streamable-http ou sse
GARMIN_MCP_HOST: endereço de bind para transportes HTTP (padrão 127.0.0.1; defina como 0.0.0.0 somente quando o endpoint estiver protegido por um proxy reverso autenticado)
GARMIN_MCP_PORT: porta de bind para transportes HTTP (padrão 8000)

GARMIN_MCP_TRANSPORT=streamable-http garmin-mcp

Quando um transporte HTTP é selecionado:

Os clientes MCP se conectam ao caminho /mcp (por exemplo, http://localhost:8000/mcp).
Um endpoint GET /healthz simples é exposto para sondagens de liveness/readiness.

O servidor em si não realiza autenticação no endpoint HTTP — coloque-o atrás de um proxy reverso (nginx, Traefik, Authelia etc.) se ele estiver acessível além do localhost.

Garmin Connect China (garmin.cn)

Se você usa o Garmin Connect China (garmin.cn) em vez da versão internacional, defina a variável de ambiente GARMIN_IS_CN como true:

# Pre-authenticate with Garmin Connect China
GARMIN_IS_CN=true garmin-mcp-auth

# Or use the CLI flag
garmin-mcp-auth --is-cn

Para o Claude Desktop, adicione GARMIN_IS_CN à seção env:

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ],
      "env": {
        "GARMIN_IS_CN": "true"
      }
    }
  }
}

Para Docker, adicione GARMIN_IS_CN=true ao seu arquivo .env ou descomente-o em docker-compose.yml.

Testando o servidor localmente com o MCP Inspector

O Inspector é executado diretamente via npx, sem necessidade de instalação. Execute a partir da raiz do projeto:

npx @modelcontextprotocol/inspector uv run garmin-mcp

Você poderá inspecionar e testar as ferramentas.

Com o Claude Desktop

Crie uma configuração no Claude Desktop:

Edite o arquivo de configuração do Claude Desktop:

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

Você tem duas opções para executar o MCP localmente com o Claude.

Diretamente do GitHub, sem clonar o repositório:

Adicione esta configuração de servidor:

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ],
      "env": {
        "GARMIN_EMAIL": "YOUR_GARMIN_EMAIL",
        "GARMIN_PASSWORD": "YOUR_GARMIN_PASSWORD"
      }
    }
  }
}

Talvez seja necessário adicionar o caminho completo do uvx; você pode verificar o caminho completo com which uvx

Reinicie o Claude Desktop

Diretamente da sua cópia local do repositório:

Adicione esta configuração de servidor:

{
  "mcpServers": {
    "garmin-local": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to your local repository>/garmin_mcp",
        "run",
        "garmin-mcp"
      ]
    }
  }
}

Reinicie o Claude Desktop

Com o Codex

O Codex usa TOML para configuração de servidores MCP. Adicione uma das seguintes entradas ao ~/.codex/config.toml após autenticar com garmin-mcp-auth.

Você também pode pedir ao seu cliente compatível com MCP para configurar isso para você. Por exemplo:

Install the Garmin MCP server from https://github.com/Taxuspt/garmin_mcp, authenticate with garmin-mcp-auth, and add it to my MCP configuration without storing my Garmin email or password.

Diretamente do GitHub, sem clonar o repositório

[mcp_servers.garmin]
command = "uvx"
args = [
  "--python",
  "3.12",
  "--from",
  "git+https://github.com/Taxuspt/garmin_mcp",
  "garmin-mcp"
]

Diretamente da sua cópia local do repositório

[mcp_servers.garmin-local]
command = "uv"
args = [
  "--directory",
  "/full/path/to/garmin_mcp",
  "run",
  "garmin-mcp"
]

Reinicie seu cliente MCP após salvar o arquivo.

Com o opencode

O opencode carrega automaticamente um opencode.json no nível do projeto quando iniciado a partir da raiz de um repositório, então contribuidores que clonam este repositório obtêm o Garmin MCP vinculado ao código-fonte local sem configuração adicional.

A partir de um clone deste repositório (recomendado para desenvolvimento)

Este repositório inclui um opencode.json que executa o MCP via uv run garmin-mcp, garantindo que ele sempre acompanhe a árvore de trabalho.

git clone https://github.com/Taxuspt/garmin_mcp.git
cd garmin_mcp
uv sync                # install dependencies
garmin-mcp-auth        # one-time Garmin login (skip if ~/.garminconnect already exists)
opencode               # launches with the garmin MCP attached

Verifique se o servidor está conectado:

opencode mcp list
# ●  ✓ garmin   connected
#       uv run garmin-mcp

A partir de qualquer outro diretório (instalação via GitHub)

Adicione o servidor à sua configuração global do opencode em ~/.config/opencode/opencode.json após executar garmin-mcp-auth:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "garmin": {
      "type": "local",
      "command": [
        "uvx",
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Reinicie o opencode após salvar o arquivo. A primeira invocação do uvx baixa e armazena o pacote em cache, portanto a inicialização inicial pode levar alguns segundos.

Com Docker

O Docker fornece um ambiente isolado e consistente para executar o servidor MCP.

Início rápido com Docker Compose (recomendado)

Crie um arquivo .env com suas credenciais:

echo "GARMIN_EMAIL=your_email@example.com" > .env
echo "GARMIN_PASSWORD=your_password" >> .env

Inicie o contêiner:

docker compose up -d

Visualize os logs para monitorar o servidor:

docker compose logs -f garmin-mcp

Usando Docker diretamente

# Build the image
docker build -t garmin-mcp .

# Run the container
docker run -it \
  -e GARMIN_EMAIL="your_email@example.com" \
  -e GARMIN_PASSWORD="your_password" \
  -v garmin-tokens:/root/.garminconnect \
  garmin-mcp

Usando segredos baseados em arquivos (mais seguro)

Para maior segurança, especialmente em ambientes de produção, use segredos baseados em arquivos em vez de variáveis de ambiente:

Crie um diretório de segredos e adicione suas credenciais:

mkdir -p secrets
echo "your_email@example.com" > secrets/garmin_email.txt
echo "your_password" > secrets/garmin_password.txt
chmod 600 secrets/*.txt

Edite o docker-compose.yml e descomente a seção de segredos:

services:
  garmin-mcp:
    environment:
      - GARMIN_EMAIL_FILE=/run/secrets/garmin_email
      - GARMIN_PASSWORD_FILE=/run/secrets/garmin_password
    secrets:
      - garmin_email
      - garmin_password

secrets:
  garmin_email:
    file: ./secrets/garmin_email.txt
  garmin_password:
    file: ./secrets/garmin_password.txt

Inicie o contêiner:

docker compose up -d

Gerenciando MFA com Docker

Se você tiver autenticação multifator (MFA) ativada na sua conta Garmin:

Execute o contêiner em modo interativo:

docker compose run --rm garmin-mcp

Quando solicitado, insira seu código MFA:

Garmin Connect MFA required. Please check your email/phone for the code.
Enter MFA code: 123456

Os tokens OAuth serão salvos no volume Docker (garmin-tokens), para que você não precise se autenticar novamente nas execuções subsequentes.
Após a configuração do MFA, você pode executar o contêiner normalmente:

docker compose up -d

Gerenciamento de volumes Docker

Os tokens OAuth são armazenados em um volume Docker persistente para evitar reautenticação:

# List volumes
docker volume ls

# Inspect the tokens volume
docker volume inspect garmin_mcp_garmin-tokens

# Remove the volume (will require re-authentication)
docker volume rm garmin_mcp_garmin-tokens

Usando com Claude Desktop via Docker

Para usar o servidor MCP em contêiner com o Claude Desktop, você pode configurá-lo para se comunicar com o contêiner. No entanto, observe que os servidores MCP normalmente se comunicam via stdio, o que funciona melhor com a execução direta de processos. Para implantações baseadas em Docker, considere usar o método padrão uvx mostrado na seção Com o Claude Desktop.

Exemplos de uso

Uma vez conectado no Claude, você pode fazer perguntas como:

"Mostre minhas atividades recentes"
"Como foi meu sono ontem à noite?"
"Quantos passos dei ontem?"
"Mostre os detalhes da minha corrida mais recente"
"Analise as zonas de potência do meu último pedal e compare com minhas zonas de treino"
"Mostre minha tendência de CTL, ATL e TSB nas últimas 6 semanas"
"Qual foi minha curva de duração de potência no pedal de ontem? Estime meu FTP."
"Analise os dados FIT da minha última atividade de ciclismo — como foi minha qualidade de troca de marcha nas subidas?"
"Mostre minha tendência de VFC nas últimas 2 semanas e sinalize qualquer preocupação de recuperação"
"Qual é minha melhor potência de 20 minutos da temporada e quando eu a alcancei?"

Solução de problemas

"Falha ao gerar processo: arquivo ou diretório não encontrado"

Se o Claude Desktop não conseguir encontrar o uvx, é porque o uvx não está no PATH usado pelo Claude Desktop. Para corrigir:

Descubra onde o uvx está instalado:

which uvx

Use o caminho completo na sua configuração. Por exemplo, se o uvx estiver em /Users/username/.cargo/bin/uvx:

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/username/.cargo/bin/uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ]
    }
  }
}

Problemas de login

Se você encontrar problemas de login:

Verifique se suas credenciais estão corretas
Verifique se o Garmin Connect exige verificação adicional
Garanta que o pacote garminconnect esteja atualizado

Logs

Para outros problemas, verifique os logs do Claude Desktop em:

macOS: ~/Library/Logs/Claude/mcp-server-garmin.log
Windows: %APPDATA%\Claude\logs\mcp-server-garmin.log

Autenticação Multifator (MFA) do Garmin Connect

Entendendo o MFA com servidores MCP

Os servidores MCP são executados como processos em segundo plano, sem acesso direto ao terminal. Se sua conta Garmin tiver MFA ativado, você deve se autenticar uma vez usando a ferramenta de pré-autenticação antes que o servidor possa ser executado.

Recomendado: ferramenta de pré-autenticação

A maneira mais fácil de lidar com MFA é usar a ferramenta de autenticação dedicada:

garmin-mcp-auth

Isso salva os tokens OAuth em ~/.garminconnect para uso futuro. O servidor usará automaticamente esses tokens ao ser executado no Claude Desktop ou em outros clientes MCP.

Opções adicionais:

# Use environment variables for credentials
GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=secret garmin-mcp-auth

# Verify existing tokens
garmin-mcp-auth --verify

# Force re-authentication (e.g., when tokens expire)
garmin-mcp-auth --force-reauth

# Use custom token location
garmin-mcp-auth --token-path ~/.garmin_tokens

Alternativa: primeira execução manual

Você também pode se autenticar executando o servidor uma vez de forma interativa:

# Store credentials in files for security
echo "your_email@example.com" > ~/.garmin_email
echo "your_password" > ~/.garmin_password
chmod 600 ~/.garmin_email ~/.garmin_password

# Run server interactively to authenticate
GARMIN_EMAIL_FILE=~/.garmin_email GARMIN_PASSWORD_FILE=~/.garmin_password \
  uvx --python 3.12 --from git+https://github.com/Taxuspt/garmin_mcp garmin-mcp

# Enter MFA code when prompted
# Tokens will be saved automatically
# Now add to Claude Desktop config without credentials

Após a autenticação inicial, configure o Claude Desktop sem credenciais (os tokens já estão salvos):

{
  "mcpServers": {
    "garmin": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/Taxuspt/garmin_mcp",
        "garmin-mcp"
      ]
    }
  }
}

Usando Docker com MFA

Se você estiver usando Docker, siga a seção Gerenciando MFA com Docker acima para uma experiência simplificada com armazenamento persistente de tokens.

Solução de problemas de MFA

Erro: "Autenticação MFA necessária, mas nenhum terminal interativo disponível"

Solução:

Abra o terminal
Execute: garmin-mcp-auth
Insira as credenciais e o código MFA
Reinicie o Claude Desktop

Token expirado

Os tokens OAuth expiram periodicamente (aproximadamente a cada 6 meses). Reautentique:

garmin-mcp-auth --force-reauth

Verifique se os tokens funcionam

garmin-mcp-auth --verify

Testes

Este projeto inclui testes abrangentes para todas as ferramentas MCP. Todos os testes estão passando atualmente (100%).

Executando os testes

# Run all integration tests (default - uses mocked Garmin API)
uv run pytest tests/integration/

# Run tests with verbose output
uv run pytest tests/integration/ -v

# Run a specific test module
uv run pytest tests/integration/test_health_wellness_tools.py -v

# Run end-to-end tests (requires real Garmin credentials)
uv run pytest tests/e2e/ -m e2e -v

Estrutura dos testes

Testes de integração (mais de 200 testes): testam todas as ferramentas MCP usando integração FastMCP com respostas simuladas da API Garmin
Testes de ponta a ponta (4 testes): testam com servidor MCP real e API Garmin (exigem credenciais válidas)

Reinstalando a partir do caminho local

Se você estiver trabalhando a partir de um checkout ou fork local:

uv tool install --python 3.12 --force C:\Users\aresd\Desktop\programacion\garmin_mcp

Garmin MCP Server

Documentação

Garmin MCP Server

Recursos

Cobertura de Ferramentas

Downloads de Arquivos de Atividade

Endpoints Intencionalmente Ignorados

Filtragem de Ferramentas

Ferramentas de treino de alto nível

create_walk_run_workout

create_z2_walk_workout

create_strength_workout

schedule_week

Exemplo de fluxo completo

Condições de término brutas do upload_workout

Tipos de alvo brutos do upload_workout

Instalação com um clique (Claude Desktop)

Baixar e instalar

Autenticação na primeira vez

Crie o .dxt você mesmo

Configuração

Início Rápido para Clientes MCP

Pré-requisitos

Etapa 1: Pré-autenticação (única vez)

Etapa 2: Configurar o Claude Desktop

Etapa 3: Reinicie seu cliente MCP

Configuração de Desenvolvimento

Executando o Servidor

Configuração

Transporte

Garmin Connect China (garmin.cn)

Testando o servidor localmente com o MCP Inspector

Com o Claude Desktop

Diretamente do GitHub, sem clonar o repositório:

Diretamente da sua cópia local do repositório:

Com o Codex

Diretamente do GitHub, sem clonar o repositório

Diretamente da sua cópia local do repositório

Com o opencode

A partir de um clone deste repositório (recomendado para desenvolvimento)

A partir de qualquer outro diretório (instalação via GitHub)

Com Docker

Início rápido com Docker Compose (recomendado)

Usando Docker diretamente

Usando segredos baseados em arquivos (mais seguro)

Gerenciando MFA com Docker

Gerenciamento de volumes Docker

Usando com Claude Desktop via Docker

Exemplos de uso

Solução de problemas

"Falha ao gerar processo: arquivo ou diretório não encontrado"

Problemas de login

Logs

Autenticação Multifator (MFA) do Garmin Connect

Entendendo o MFA com servidores MCP

Recomendado: ferramenta de pré-autenticação

Alternativa: primeira execução manual

Usando Docker com MFA

Solução de problemas de MFA

Testes

Executando os testes

Estrutura dos testes

Reinstalando a partir do caminho local

`create_walk_run_workout`

`create_z2_walk_workout`

`create_strength_workout`

`schedule_week`

Condições de término brutas do `upload_workout`

Tipos de alvo brutos do `upload_workout`

Crie o `.dxt` você mesmo