README.md•5.38 kB
# 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
```bash
curl https://mcp-evolution-api-fixed-production.up.railway.app/
```
### 2. Estado de Salud
```bash
curl https://mcp-evolution-api-fixed-production.up.railway.app/api/health \
-H "X-API-Key: BC10D87095B7-44E2-B1A4-F03BE2BECE24"
```
### 3. Listar Instancias
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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:
```bash
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
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:
```bash
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