Evolution API MCP Server - Guía de Uso

Configuración Actual

• URL del Servidor MCP: https://mcp-evolution-api-fixed-production.up.railway.app

• URL de Evolution API: https://evolution-api-evolution-api.dqyvuv.easypanel.host

• API Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24

• Instancia: Luis2

• Número de prueba: 554198908495

Endpoints Disponibles

1. Información del Servidor

curl https://mcp-evolution-api-fixed-production.up.railway.app/

2. Estado de Salud

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/health \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

3. Listar Instancias

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

4. Estado de una Instancia

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances/Luis2/status \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

5. Enviar Mensaje de Texto

curl -X POST https://mcp-evolution-api-fixed-production.up.railway.app/api/send/text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24" \
  -d '{
    "instanceName": "Luis2",
    "number": "554198908495",
    "text": "Hola! Este es un mensaje de prueba"
  }'

6. Verificar Números de WhatsApp

curl -X POST https://mcp-evolution-api-fixed-production.up.railway.app/api/check-numbers \
  -H "Content-Type: application/json" \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24" \
  -d '{
    "instanceName": "Luis2",
    "numbers": ["554198908495", "5541999999999"]
  }'

7. Listar Contactos

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances/Luis2/contacts \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

8. Listar Grupos

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances/Luis2/groups \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

9. Listar Chats

curl https://mcp-evolution-api-fixed-production.up.railway.app/api/instances/Luis2/chats \
  -H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

Solución de Problemas

El mensaje no llega a WhatsApp

1. Verificar que la instancia esté conectada:

   • La instancia debe tener estado "open" o "connected"

   • Si no está conectada, necesitas escanear el código QR nuevamente

2. Formato del número:

   • Brasil: 55 + código de área + número (ejemplo: 554198908495)

   • Sin espacios, guiones o símbolos

   • Sin el símbolo + al inicio

3. Verificar si el número tiene WhatsApp:

   • Usa el endpoint /api/check-numbers para verificar

Error "Access denied"

• Verifica que estés enviando el header X-API-Key con el valor correcto

• El API Key debe ser: BC10D87095B7-44E2-B1A4-F03BE2BECE24

Error de conexión

1. Verifica que Evolution API esté funcionando:

   curl https://evolution-api-evolution-api.dqyvuv.easypanel.host/instance/fetchInstances \
     -H "apikey: BC10D87095B7-44E2-B1A4-F03BE2BECE24"

2. Si Evolution API no responde, el problema está en Easypanel

Scripts de Prueba

Hay dos scripts de prueba disponibles:

1. test-mcp.sh - Prueba el servidor MCP

2. test-evolution-direct.sh - Prueba directamente Evolution API

Para ejecutarlos en Windows, usa Git Bash:

bash test-mcp.sh
bash test-evolution-direct.sh

Actualización del Código

Cuando hagas cambios en el código:

1. Commit y push a GitHub:

   git add .
   git commit -m "Descripción del cambio"
   git push origin master

2. Railway detectará automáticamente los cambios y redesplegará

3. Verifica el estado del deployment en Railway:

   • Ve a https://railway.app

   • Entra al proyecto "MCP Servers"

   • Revisa el estado del deployment

Estructura del Proyecto

evolution-api-mcp-server/
├── src/
│   ├── index.ts           # Archivo principal
│   ├── routes/
│   │   └── api.ts         # Rutas HTTP de la API
│   ├── services/
│   │   ├── evolution-api.ts  # Cliente de Evolution API
│   │   └── template-service.ts # Servicio de templates
│   └── types/
│       └── evolution.ts    # Tipos TypeScript
├── package.json
├── tsconfig.json
├── Dockerfile
└── .env                   # Variables de entorno (local)

Variables de Entorno en Railway

Las siguientes variables están configuradas en Railway:

• EVOLUTION_API_URL: https://evolution-api-evolution-api.dqyvuv.easypanel.host

• EVOLUTION_API_KEY: BC10D87095B7-44E2-B1A4-F03BE2BECE24

• MCP_SERVER_PORT: 3000

• NODE_ENV: production

Notas Importantes

1. Seguridad: Nunca expongas el API Key en código público

2. Rate Limiting: Evolution API puede tener límites de tasa

3. Sesión de WhatsApp: La sesión puede expirar y requerir nuevo escaneo de QR

4. Números bloqueados: WhatsApp puede bloquear números que envían muchos mensajes

Contacto y Soporte

Para problemas con:

• Evolution API: Revisa la documentación en https://doc.evolution-api.com

• Railway: https://railway.app/support

• Easypanel: Panel de control de tu instancia

Última actualización: 14 de Septiembre de 2025