npm package: @marcelocorrea/mcp-evolution-api
Description: MCP Server para integração com Evolution API WhatsApp
Author: Marcelo
Latest version: 1.0.3

# 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

```bash
# Instalar dependências
npm install

# Compilar o projeto
npm run build
```

## ⚙️ Configuração

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

```bash
cp .env.example .env
```

2. Configure as variáveis de ambiente:

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

## 🔧 Uso

### Desenvolvimento

```bash
npm run dev
```

### Produção

```bash
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)

```json
{
  "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

```json
{
  "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

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

### Criar grupo

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

### Enviar mídia

```typescript
{
  "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](https://doc.evolution-api.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Anthropic Claude](https://www.anthropic.com/)