MCP Evolution API

MCP Evolution API

Un servidor de Model Context Protocol (MCP) para Claude que se integra con Evolution API para la automatización de WhatsApp.

Resumen

Este servidor MCP permite a Claude interactuar con WhatsApp a través de Evolution API, habilitando capacidades como:

• Gestión de instancias de WhatsApp
• Envío de varios tipos de mensajes
• Trabajo con contactos y grupos
• Configuración de webhooks y ajustes

📂 Estructura del Proyecto

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

🚀 Configuración Rápida

Configuración del Entorno

Crea un archivo .env con tus credenciales de Evolution API:

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

Nota: proporcionaste la URL de la API y una clave. Por seguridad, nunca confirmes claves de API reales en el repositorio ni las compartas públicamente. Usa un archivo .env local o un gestor de secretos en producción.

📋 Opciones de Despliegue

Entorno	Pasos	Comando
Desarrollo Local	1. Clonar e instalar 2. Ejecutar en modo desarrollo	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run dev
Producción Local	1. Clonar e instalar 2. Compilar y ejecutar	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	Ejecutar con Docker Compose	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api docker-compose up -d
Docker	Compilar y ejecutar contenedor	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

Configuración de Claude Desktop

Agrega esto a tu archivo de configuración de Claude Desktop (ubicado típicamente en ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Si usas el despliegue con Docker:

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

📊 Estado de Implementación

Categoría	Implementado	Pendiente de Implementación
API Principal	✅ Obtener Información ✅ Crear Instancia ✅ Obtener Instancias ✅ Conectar Instancia ✅ Reiniciar Instancia ✅ Estado de Conexión ✅ Cerrar Sesión de Instancia ✅ Eliminar Instancia ✅ Establecer Presencia	❌ Verificar si es WhatsApp
Webhook y Ajustes	✅ Establecer Webhook ✅ Buscar Webhook ✅ Establecer Ajustes ✅ Buscar Ajustes
Mensajería	✅ Enviar Texto Plano ✅ Enviar Estado ✅ Enviar Multimedia ✅ Enviar Audio de WhatsApp ✅ Enviar Sticker ✅ Enviar Ubicación ✅ Enviar Contacto ✅ Enviar Reacción ✅ Enviar Encuesta ✅ Enviar Lista ✅ Enviar Botones	❌ Marcar Mensaje como Leído ❌ Marcar Mensaje como No Leído ❌ Archivar Chat ❌ Eliminar Mensaje para Todos ❌ Actualizar Mensaje ❌ Enviar Presencia (Control de Chat)
Chat y Contactos	✅ Buscar Contactos ✅ Buscar Chats	❌ Actualizar Estado de Bloqueo ❌ Obtener URL de Foto de Perfil ❌ Obtener Base64 ❌ Buscar Mensajes ❌ Buscar Mensaje de Estado
Grupos	✅ Buscar Grupo por JID ✅ Obtener Todos los Grupos ✅ Buscar Miembros del Grupo	❌ Crear Grupo ❌ Actualizar Foto del Grupo ❌ Actualizar Asunto del Grupo ❌ Actualizar Descripción del Grupo ❌ Obtener Código de Invitación ❌ Revocar Código de Invitación ❌ Enviar Invitación al Grupo ❌ Buscar Grupo por Código de Invitación ❌ Actualizar Miembros del Grupo ❌ Actualizar Configuración del Grupo ❌ Alternar Efímero ❌ Salir del Grupo
Ajustes de Perfil		❌ Obtener Perfil de Negocio ❌ Obtener Perfil ❌ Actualizar Nombre de Perfil ❌ Actualizar Estado de Perfil ❌ Actualizar Foto de Perfil ❌ Eliminar Foto de Perfil ❌ Obtener Ajustes de Privacidad ❌ Actualizar Ajustes de Privacidad
Integraciones de Bot		❌ Integraciones Typebot ❌ Integraciones OpenAI ❌ Evolution Bot ❌ Dify Bot ❌ Flowise Bot
Otras Integraciones		❌ Chatwoot ❌ Websocket ❌ SQS ❌ RabbitMQ

Para más información, consulta la Documentación de Evolution API.

Ejemplos

• examples/hono-bun/ - pequeño servidor Hono para Bun (ejemplo guardado). Vea examples/hono-bun/README.md para instrucciones de ejecución.