MCP Evolution API

Servidor MCP (Model Context Protocol) para integração com a Evolution API - WhatsApp Business API.

📋 Características

Este servidor MCP fornece ferramentas para interagir com a Evolution API, permitindo:

Gerenciamento de Instâncias

• ✅ Criar, conectar, reiniciar e deletar instâncias
• ✅ Verificar status de conexão
• ✅ Logout de instâncias

Mensagens

• ✅ Enviar mensagens de texto
• ✅ Enviar mídias (imagem, vídeo, documento)
• ✅ Enviar contatos
• ✅ Enviar localização
• ✅ Enviar botões interativos
• ✅ Enviar enquetes
• ✅ Enviar stickers
• ✅ Deletar mensagens

Chat

• ✅ Verificar números do WhatsApp
• ✅ Buscar contatos
• ✅ Buscar mensagens
• ✅ Buscar conversas
• ✅ Marcar mensagens como lidas
• ✅ Arquivar conversas

Grupos

• ✅ Criar grupos
• ✅ Atualizar nome e descrição
• ✅ Gerenciar códigos de convite
• ✅ Atualizar foto do grupo

Perfil

• ✅ Atualizar nome do perfil
• ✅ Atualizar status
• ✅ Atualizar foto de perfil
• ✅ Gerenciar configurações de privacidade

🚀 Instalação

# Instalar dependências
npm install

# Compilar o projeto
npm run build

⚙️ Configuração

1. Copie o arquivo .env.example para .env:

cp .env.example .env

2. Configure as variáveis de ambiente:

EVOLUTION_API_URL=http://localhost:8080
EVOLUTION_API_KEY=sua-chave-api-aqui
EVOLUTION_INSTANCE_NAME=minha-instancia

🔧 Uso

Desenvolvimento

npm run dev

Produção

npm start

🔌 Configuração no Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop (claude_desktop_config.json):

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

Usando NPX (Recomendado)

{
  "mcpServers": {
    "evolution-api": {
      "command": "npx",
      "args": ["-y", "@marcelocorrea/mcp-evolution-api"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "sua-chave-api",
        "EVOLUTION_INSTANCE_NAME": "minha-instancia"
      }
    }
  }
}

Usando caminho local

{
  "mcpServers": {
    "evolution-api": {
      "command": "node",
      "args": ["/caminho/completo/para/mcp-evolution-api/dist/index.js"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "sua-chave-api",
        "EVOLUTION_INSTANCE_NAME": "minha-instancia"
      }
    }
  }
}

📚 Ferramentas Disponíveis

Instâncias

• create_instance - Criar nova instância
• fetch_instances - Listar instâncias
• connect_instance - Conectar e obter QR Code
• get_connection_status - Status da conexão
• restart_instance - Reiniciar instância
• logout_instance - Deslogar
• delete_instance - Deletar instância

Mensagens

• send_text - Enviar texto
• send_media - Enviar mídia
• send_contact - Enviar contato
• send_location - Enviar localização
• send_buttons - Enviar botões
• send_poll - Enviar enquete
• send_sticker - Enviar sticker

Chat

• check_whatsapp_numbers - Verificar números
• find_contacts - Buscar contatos
• find_messages - Buscar mensagens
• find_chats - Buscar conversas
• delete_message - Deletar mensagem

Grupos

• create_group - Criar grupo
• update_group_subject - Atualizar nome
• fetch_invite_code - Obter código de convite

Perfil

• update_profile_name - Atualizar nome
• update_profile_status - Atualizar status
• fetch_privacy_settings - Buscar configurações de privacidade

Configurações

• set_settings - Configurar instância
• find_settings - Buscar configurações

📝 Exemplos de Uso

Enviar mensagem de texto

{
  "number": "5511999999999",
  "text": "Olá! Esta é uma mensagem de teste."
}

Criar grupo

{
  "subject": "Meu Grupo",
  "description": "Descrição do grupo",
  "participants": ["5511999999999", "5511888888888"]
}

Enviar mídia

{
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://exemplo.com/imagem.jpg",
  "caption": "Legenda da imagem"
}

🛠️ Tecnologias

• TypeScript - Linguagem principal
• Model Context Protocol SDK - Framework MCP
• Axios - Cliente HTTP
• Zod - Validação de schemas

📄 Licença

MIT

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues e pull requests.

🔗 Links Úteis

• Evolution API Documentation
• Model Context Protocol
• Anthropic Claude