hevy-mcp-server

henrique-franze/hevy-mcp-server

3.1

If you are the rightful owner of hevy-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Hevy MCP Server is designed to integrate with the Hevy API, enabling the management and prescription of workouts through natural language commands.

Hevy MCP Server

MCP (Model Context Protocol) server para integração com a API do Hevy, permitindo administração e prescrição de treinos através de Claude.

Visão Geral

Este projeto implementa um servidor MCP que se conecta à API do Hevy para gerenciar treinos e rotinas de exercícios. O foco principal é permitir a criação, edição e organização de treinos completos através de comandos naturais.

Terminologia

Hevy API → Português

  • RoutineFolders = Treinos (conjunto completo de rotinas)
  • Routines = Rotinas Diárias (treino específico de um dia)
  • Exercises = Exercícios (movimentos individuais)
  • Workouts = Treinos Executados (dados históricos)

Estrutura Hierárquica

TREINO (RoutineFolder)
├── Rotina Dia 1 (Routine) - Ex: "Peito, Ombros & Tríceps"
│   ├── Exercício 1 - Ex: "Supino com Barra"
│   │   ├── Série W (Warm up)
│   │   ├── Série 1 (Normal)
│   │   ├── Série F (Failure)
│   │   └── Série D (Drop)
│   └── Exercício 2...
├── Rotina Dia 2 (Routine) - Ex: "Costas & Bíceps"
└── Rotina Dia 3 (Routine) - Ex: "Pernas & Abs"

Funcionalidades - Fase 1

Gestão de Treinos (RoutineFolders)

  • ✅ Listar treinos existentes
  • ✅ Criar novos treinos
  • ✅ Editar treinos existentes
  • ✅ Deletar treinos

Gestão de Rotinas (Routines)

  • ✅ Criar rotinas diárias dentro de treinos
  • ✅ Editar rotinas existentes
  • ✅ Adicionar/remover exercícios de rotinas
  • ✅ Configurar metadados (título, tempo de descanso, notas)

Gestão de Exercícios

  • ✅ Consultar biblioteca de exercícios disponíveis
  • ✅ Adicionar exercícios às rotinas
  • ✅ Configurar séries por exercício
  • ✅ Suporte a diferentes tipos de séries:
    • W = Warm up (aquecimento)
    • 1-9 = Normal (séries normais numeradas)
    • F = Failure (até a falha)
    • D = Drop (drop set)

Configuração de Séries

  • ✅ Definir peso (KG)
  • ✅ Configurar repetições:
    • Rep Range (ex: 6-10)
    • Reps (número fixo)
  • ⚠️ Restrição: Todas as séries de um exercício devem usar o mesmo tipo de repetição

Não Incluído na Fase 1

  • ❌ Workouts (treinos executados) - para relatórios futuros
  • ❌ Webhooks - desnecessário agora
  • ❌ Análise de dados históricos

Pré-requisitos

  • Python 3.8+
  • Hevy Pro subscription (necessário para API key)
  • API key do Hevy

Instalação

# Clone o repositório
git clone https://github.com/henrique-franze/hevy-mcp-server.git
cd hevy-mcp-server

# Instale as dependências
pip install -r requirements.txt

# Configure a API key
export HEVY_API_KEY="sua_api_key_aqui"

Uso

# Inicie o servidor MCP
python server.py

Documentação da API Hevy

A API do Hevy possui 18 endpoints principais organizados em 5 categorias:

  • Workouts (4 endpoints)
  • Routines (6 endpoints)
  • ExerciseTemplates (4 endpoints)
  • RoutineFolders (2 endpoints)
  • Webhook (2 endpoints)

Documentação completa: https://api.hevyapp.com/docs/

Contribuição

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
  3. Commit suas mudanças (git commit -m 'Adiciona nova funcionalidade')
  4. Push para a branch (git push origin feature/nova-funcionalidade)
  5. Abra um Pull Request

Licença

MIT License - veja o arquivo para detalhes.