MCP EVO - Model Context Protocol para Academia EVO

Este projeto implementa um servidor MCP (Model Context Protocol) para integração com a API EVO, permitindo que você use todas as funcionalidades da academia diretamente no n8n ou outros clientes MCP.

🚀 Funcionalidades

Controle de Acesso

• authorize_entry - Autoriza ou nega acesso de usuários à academia

• get_turnstiles - Lista catracas disponíveis

Gestão de Membros

• get_member_profile - Busca perfil de um membro

• get_members - Lista todos os membros ativos

• authenticate_member - Autentica membros com email/senha

• update_member_card - Atualiza número do cartão

• block_unblock_member - Bloqueia/desbloqueia membros

Atividades e Cronograma

• get_activities - Lista atividades disponíveis

• get_activity_schedule - Busca cronograma de atividades

• enroll_member_in_activity - Inscreve membros em atividades

• get_activity_spots - Verifica vagas disponíveis

Vendas e Carrinhos

• get_cart - Busca carrinho por token

• create_cart - Cria novo carrinho

• get_sales - Lista vendas por período

• create_sale - Cria nova venda

Treinos

• get_workouts - Busca treinos de clientes

• link_workout_to_client - Vincula treino ao cliente

• update_workout - Atualiza dados do treino

Utilitários

• health_check - Verifica status da API

• get_configuration - Busca configurações da filial

Related MCP server: aidoo-mcp-server

📋 Pré-requisitos

• Node.js 18+

• npm ou yarn

• Acesso à API EVO com credenciais válidas

🛠️ Instalação

1. Clone o repositório e instale as dependências:

git clone <seu-repositorio>
cd evo-mcp
npm install

2. Configure as variáveis de ambiente:

cp env.example .env

Edite o arquivo .env com suas credenciais:

EVO_API_URL=https://evo-integracao-api.w12app.com.br
EVO_DNS=a2academia
EVO_TOKEN=DA67E8B5-0628-40C2-B586-A20A0462F1E4

3. Compile o projeto:

npm run build

🚀 Como usar

Executar localmente

npm start

Executar em modo desenvolvimento

npm run dev

🔧 Configuração no n8n

1. Adicione a configuração MCP no seu n8n:

{
  "mcpServers": {
    "evo": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/caminho/para/seu/projeto/evo-mcp",
      "env": {
        "EVO_API_URL": "https://evo-integracao-api.w12app.com.br",
        "EVO_DNS": "a2academia",
        "EVO_TOKEN": "DA67E8B5-0628-40C2-B586-A20A0462F1E4"
      }
    }
  }
}

2. Reinicie o n8n

3. Use as ferramentas MCP nos seus workflows:

   • Controle de acesso automático

   • Gestão de membros

   • Agendamento de atividades

   • Relatórios de vendas

   • Gestão de treinos

📖 Exemplos de Uso

Autorizar Entrada de Membro

{
  "tool": "authorize_entry",
  "arguments": {
    "userId": 12345,
    "personType": 1,
    "device": 2,
    "turnstileId": 202,
    "temperature": 36.5,
    "climateId": 1
  }
}

Buscar Perfil de Membro

{
  "tool": "get_member_profile",
  "arguments": {
    "memberId": 12345
  }
}

Listar Atividades

{
  "tool": "get_activities",
  "arguments": {}
}

🔒 Segurança

• Nunca compartilhe seu token EVO

• Use variáveis de ambiente para credenciais

• Mantenha o projeto atualizado

• Monitore logs de acesso

🐛 Troubleshooting

Erro de Conexão

• Verifique se a API EVO está acessível

• Confirme se o DNS e token estão corretos

• Teste com health_check

Erro de Compilação

• Verifique se o Node.js está na versão 18+

• Execute npm install novamente

• Limpe a pasta dist e recompile

Erro no n8n

• Verifique se o caminho do MCP está correto

• Confirme se as variáveis de ambiente estão definidas

• Verifique os logs do n8n

📝 Logs

O MCP registra todas as operações:

• Requisições à API EVO

• Respostas e erros

• Status de conexão

• Operações realizadas

🤝 Contribuição

1. Fork o projeto

2. Crie uma branch para sua feature

3. Commit suas mudanças

4. Push para a branch

5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🆘 Suporte

Para suporte técnico:

• Abra uma issue no GitHub

• Consulte a documentação da API EVO

• Verifique os logs de erro

Desenvolvido para integração com a API EVO - Sistema de Gestão para Academias