Garmin Connect

Acesse os dados de corrida e informações do plano de treinamento do Garmin Connect.

Documentação

garmin-mcp

Servidor MCP (Model Context Protocol) que fornece dados de corrida do Garmin Connect para LLMs.

Integra-se a clientes MCP como o Claude Desktop para realizar análise de treinos de corrida, planejamento, criação de treinos e muito mais.

Principais recursos

Consulta de atividades de corrida - atividades recentes, consulta por data, análise detalhada, dados de splits (47 campos: ritmo, FC, cadência, dinâmicas de corrida, potência, zonas de FC, GAP, inclinação, resistência, temperatura etc.)
Análise de trail running - análise de segmentos de inclinação ClimbPro, dificuldade por grau, ritmo ajustado por inclinação (GAP), detecção de corrida/caminhada, condições climáticas
Resumo semanal/mensal - tendência de volume, comparação com o mês anterior
Métricas de treino - VO2max, status de treino, prontidão para treino, previsão de corrida, limiar de lactato
FC/HRV - FC diária, variabilidade da frequência cardíaca, distribuição de zonas de FC por atividade
Bem-estar - sono, estresse, Body Battery, SpO2
Recordes pessoais/metas - PR, metas de condicionamento físico
Criação de treinos - treinos estruturados baseados em tempo/distância, intervalos, ritmo etc., enviados para o relógio Garmin (alvos de ritmo/FC/cadência/potência)
Gerenciamento de tênis de corrida - distância acumulada por tênis + rastreamento de desgaste
Privacidade - filtragem automática de PII (nome do proprietário, ID do perfil, coordenadas GPS) em todas as respostas da API

Requisitos

Python 3.10+
Gerenciador de pacotes uv
Conta Garmin Connect

Instalação

git clone https://github.com/leewnsdud/garmin-connect-mcp.git
cd garmin-connect-mcp
uv sync

Autenticação

É necessária uma autenticação única inicial.

uv run python scripts/auth.py

Ao inserir e-mail e senha, o token OAuth é salvo em ~/.garminconnect/. Ao usar MFA, um prompt de inserção de código será exibido.

Se o token expirar, execute novamente ou defina as credenciais no arquivo .env para renovação automática.

Integração com Claude Desktop

Adicione em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "garmin-mcp": {
      "command": "/Users/<username>/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/garmin-mcp",
        "run",
        "garmin-mcp"
      ]
    }
  }
}

Use o caminho completo de uv. Verifique com which uv.

Após a configuração, reinicie o Claude Desktop para ativar as ferramentas.

Variáveis de ambiente (opcional)

Consulte .env.example para criar o arquivo .env.

Variável	Descrição	Padrão
`GARMIN_EMAIL`	E-mail do Garmin Connect	-
`GARMIN_PASSWORD`	Senha do Garmin Connect	-
`GARMIN_TOKEN_DIR`	Caminho de armazenamento do token	`~/.garminconnect`
`GARMINTOKENS`	Token codificado em Base64 (para CI/Docker)	-

Ferramentas fornecidas (24)

Activities

Ferramenta	Descrição	Principais parâmetros
`get_recent_activities`	Lista de atividades de corrida recentes (inclui GAP, RWD)	`count` (padrão 20, máximo 100)
`get_activities_by_date`	Consulta de atividades de corrida por intervalo de datas	`start_date`, `end_date`
`get_activity_detail`	Informações detalhadas da atividade (inclui resistência, carga de impacto)	`activity_id`
`get_activity_splits`	Dados de splits por km	`activity_id`
`get_activity_weather`	Condições climáticas durante a atividade (temperatura, umidade, velocidade do vento)	`activity_id`
`get_activity_typed_splits`	Análise de segmentos de inclinação ClimbPro (grau, GAP)	`activity_id`

Summary

Ferramenta	Descrição	Principais parâmetros
`get_weekly_running_summary`	Resumo semanal de corrida	`end_date`, `weeks` (máximo 12)
`get_monthly_running_summary`	Resumo mensal de corrida + comparação com o mês anterior	`year`, `month`

Training

Ferramenta	Descrição	Principais parâmetros
`get_training_status`	Status de treino	`date`
`get_training_readiness`	Pontuação de prontidão para treino	`date`
`get_vo2max_and_fitness`	VO2max + idade de condicionamento físico	`date`
`get_race_predictions`	Previsão de recordes 5K/10K/meia/maratona	Nenhum
`get_lactate_threshold`	FC/ritmo de limiar de lactato	`start_date`, `end_date`

Heart Rate

Ferramenta	Descrição	Principais parâmetros
`get_heart_rate_data`	Dados diários de FC	`date`
`get_hrv_data`	Variabilidade da frequência cardíaca (HRV)	`date`
`get_activity_hr_zones`	Distribuição de zonas de FC por atividade	`activity_id`

Wellness

Ferramenta	Descrição	Principais parâmetros
`get_sleep_data`	Dados de sono	`date`
`get_daily_wellness`	Estresse/Body Battery/SpO2/frequência respiratória	`date`
`get_weekly_wellness_summary`	Tendência semanal de bem-estar	`end_date`, `weeks` (máximo 4)

Records & Goals

Ferramenta	Descrição	Principais parâmetros
`get_personal_records`	Recordes pessoais (1K a maratona)	Nenhum
`get_goals`	Metas de condicionamento físico	`status` (active/completed/all)

Workout

Ferramenta	Descrição	Principais parâmetros
`create_running_workout`	Criação de treino e upload para Garmin (baseado em tempo/distância, alvos de ritmo/FC/cadência/potência)	`name`, `steps`, `description`
`get_workouts`	Lista de treinos salvos	`count` (padrão 20, máximo 100)

Gear

Ferramenta	Descrição	Principais parâmetros
`get_running_gear`	Lista de tênis de corrida + distância acumulada + desgaste	Nenhum

Guia de criação de treinos

Com create_running_workout, você pode criar treinos de corrida estruturados e sincronizá-los com o relógio Garmin.

Tipos de Step

Tipo	Descrição
`warmup`	Aquecimento
`interval`	Intervalo (alta intensidade)
`recovery`	Trote de recuperação
`rest`	Descanso total (parado)
`cooldown`	Desaquecimento
`repeat`	Grupo de repetições

Condições de término (duração do Step)

Campo	Tipo	Descrição	Exemplo
`duration_seconds`	int	Baseado em tempo	`"duration_seconds": 300` (5 minutos)
`distance_meters`	int	Baseado em distância	`"distance_meters": 1000` (1 km)

É possível misturar steps baseados em tempo/distância em um único treino.

Tipos de Target

Tipo	Formato do valor	Exemplo
`pace`	min:sec/km	`"min": "4:30", "max": "4:50"`
`heart_rate`	bpm	`"min": 140, "max": 155`
`cadence`	spm	`"min": 170, "max": 185`
`power`	watts	`"min": 280, "max": 320`

Opções

Memorando do treino: adicione uma descrição completa com o parâmetro description
Memorando do Step: adicione "description": "메모" a cada step
Pular recuperação final: adicione "skip_last_rest": true ao step de repetição

Exemplo: intervalo de 4x1km baseado em distância

{
  "name": "4x1km Intervals @4:30",
  "description": "10K 레이스 대비 VO2max 인터벌",
  "steps": [
    {
      "type": "warmup",
      "duration_seconds": 600,
      "description": "가볍게 조깅"
    },
    {
      "type": "repeat",
      "count": 4,
      "skip_last_rest": true,
      "steps": [
        {
          "type": "interval",
          "distance_meters": 1000,
          "target": { "type": "pace", "min": "4:20", "max": "4:40" },
          "description": "목표 페이스 유지"
        },
        {
          "type": "recovery",
          "duration_seconds": 120,
          "description": "천천히 조깅으로 회복"
        }
      ]
    },
    {
      "type": "cooldown",
      "duration_seconds": 600,
      "description": "마무리 조깅"
    }
  ]
}

Para o guia detalhado de criação de treinos, consulte AGENTS.md; para a especificação completa de solicitações/respostas das ferramentas, consulte TOOL_SPEC.md.

Exemplos de uso

No Claude Desktop, você pode usar da seguinte forma:

"Resuma minha corrida desta semana"
"Analise a tendência de volume semanal dos últimos 3 meses"
"Calcule meu ritmo de treino Jack Daniels VDOT com base no meu VO2max"
"Verifique a distribuição de zonas de FC das atividades recentes e se estou mantendo a proporção 80/20"
"Crie um treino de intervalo 4x1km para amanhã"
"Verifique se algum dos meus tênis de corrida precisa ser substituído"
"Analise a correlação entre sono e prontidão para treino"
"Analise meu desempenho por segmento de inclinação nos trail runs recentes"
"Verifique a proporção de caminhada/corrida no trail running"

Metodologias de treino de corrida suportadas

Metodologia	Dados utilizados
Jack Daniels VDOT	VO2max, PR, previsão de corrida
Norwegian Double Threshold	Limiar de lactato, zonas de FC
80/20 Training	Distribuição de zonas de FC
Hanson's Method	Volume semanal/mensal, tendência de ritmo
Pfitzinger	Volume semanal, análise de corridas longas
Análise de trail/ultra	Segmentos de inclinação ClimbPro, clima, RWD, GAP

Desenvolvimento

# 코드 수정 후 패키지 재설치
uv sync --reinstall-package garmin-mcp

# Claude Desktop 재시작으로 MCP 서버 반영

Privacidade

Os seguintes campos de informações pessoais são removidos automaticamente de todas as respostas da API Garmin:

Informações do proprietário: ownerId, ownerFullName, ownerDisplayName, userId, URL da imagem de perfil
ID do perfil: userProfilePK, userProfileId, profileId, profileNumber
Informações do usuário: displayName, fullName, userPro, userRoles
Coordenadas GPS: startLatitude, startLongitude, endLatitude, endLongitude

Essa filtragem é processada recursivamente pela função strip_pii() de src/garmin_mcp/sanitize.py.

Stack de tecnologia

python-garminconnect - Cliente da API Garmin Connect
FastMCP - Framework de servidor MCP
uv - Gerenciador de pacotes Python
garth - Gerenciamento de tokens OAuth

Licença

MIT