MCP Evolution API

MCP Evolution API

Um servidor Model Context Protocol (MCP) para Claude que se integra com Evolution API para automação do WhatsApp.

Visão Geral

Este servidor MCP permite que o Claude interaja com o WhatsApp através da Evolution API, habilitando recursos como:

• Gerenciamento de instâncias do WhatsApp
• Envio de vários tipos de mensagens
• Trabalho com contatos e grupos
• Configuração de webhooks e configurações

📂 Estrutura do Projeto

mcp-evo-api/
├── src/
│   ├── tools/          # MCP tools implementation for Evolution API
│   ├── utils/          # Shared utilities, including Evolution API client
│   ├── main.ts         # Server entry point
│   └── types.ts        # Shared type definitions
├── scripts/            # Helper scripts
├── biome.json          # Linting configuration
├── tsconfig.json       # TypeScript configuration
├── docker-compose.yml  # Docker Compose configuration
├── Dockerfile          # Docker build configuration
└── package.json        # Project dependencies

🚀 Configuração Rápida

Configuração do Ambiente

Crie um arquivo .env com suas credenciais da Evolution API:

EVOLUTION_API_URL=https://evo-api.decisao.ai/
EVOLUTION_API_KEY=REPLACE_WITH_YOUR_REAL_KEY

Observação: você forneceu a URL da API e uma chave. Por segurança, nunca envie chaves de API reais para o repositório ou as compartilhe publicamente. Use um arquivo .env local ou um gerenciador de segredos em produção.

📋 Opções de Implantação

Ambiente	Etapas	Comando
Desenvolvimento Local	1. Clone e instale 2. Execute em modo de desenvolvimento	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run dev
Produção Local	1. Clone e instale 2. Compile e execute	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run build && bun run dist/main.js
Docker Compose	Execute com Docker Compose	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api docker-compose up -d
Docker	Compile e execute o contêiner	docker run -d -p 3000:3000 -e EVOLUTION_API_URL=yoururl -e EVOLUTION_API_KEY=yourkey --name mcp-evo-api ghcr.io/aiteks-ltda/mcp-evo-api:latest

Configuração do Claude Desktop

Adicione isto ao arquivo de configuração do Claude Desktop (normalmente localizado em ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "evo-api": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-evo-api/dist/main.js"
      ]
    }
  }
}

Se estiver usando a implantação Docker:

{
  "mcpServers": {
    "evo-api": {
      "url": "http://localhost:3000"
    }
  }
}

📊 Status da Implementação

Categoria	Implementado	Pendente de Implementação
API Principal	✅ Obter Informações ✅ Criar Instância ✅ Buscar Instâncias ✅ Conectar Instância ✅ Reiniciar Instância ✅ Estado da Conexão ✅ Sair da Instância ✅ Excluir Instância ✅ Definir Presença	❌ Verificar se é WhatsApp
Webhook e Configurações	✅ Definir Webhook ✅ Encontrar Webhook ✅ Definir Configurações ✅ Encontrar Configurações
Mensagens	✅ Enviar Texto Simples ✅ Enviar Status ✅ Enviar Mídia ✅ Enviar Áudio do WhatsApp ✅ Enviar Figurinha ✅ Enviar Localização ✅ Enviar Contato ✅ Enviar Reação ✅ Enviar Enquete ✅ Enviar Lista ✅ Enviar Botões	❌ Marcar Mensagem como Lida ❌ Marcar Mensagem como Não Lida ❌ Arquivar Conversa ❌ Excluir Mensagem para Todos ❌ Atualizar Mensagem ❌ Enviar Presença (Controle de Conversa)
Conversas e Contatos	✅ Encontrar Contatos ✅ Encontrar Conversas	❌ Atualizar Status de Bloqueio ❌ Buscar URL da Foto de Perfil ❌ Obter Base64 ❌ Encontrar Mensagens ❌ Encontrar Mensagem de Status
Grupos	✅ Encontrar Grupo por JID ✅ Buscar Todos os Grupos ✅ Encontrar Membros do Grupo	❌ Criar Grupo ❌ Atualizar Foto do Grupo ❌ Atualizar Assunto do Grupo ❌ Atualizar Descrição do Grupo ❌ Buscar Código de Convite ❌ Revogar Código de Convite ❌ Enviar Convite de Grupo ❌ Encontrar Grupo por Código de Convite ❌ Atualizar Membros do Grupo ❌ Atualizar Configuração do Grupo ❌ Alternar Efêmero ❌ Sair do Grupo
Configurações de Perfil		❌ Buscar Perfil Comercial ❌ Buscar Perfil ❌ Atualizar Nome do Perfil ❌ Atualizar Status do Perfil ❌ Atualizar Foto do Perfil ❌ Remover Foto do Perfil ❌ Buscar Configurações de Privacidade ❌ Atualizar Configurações de Privacidade
Integrações de Bot		❌ Integrações Typebot ❌ Integrações OpenAI ❌ Evolution Bot ❌ Dify Bot ❌ Flowise Bot
Outras Integrações		❌ Chatwoot ❌ Websocket ❌ SQS ❌ RabbitMQ

Para mais informações, consulte a Documentação da Evolution API.

Exemplos

• examples/hono-bun/ - pequeno servidor Hono para Bun (exemplo salvo). Veja examples/hono-bun/README.md para instruções de execução.