La mayoría de los tutoriales de WhatsApp MCP se detienen en Claude Desktop. Esta guía de Whapi.Cloud está escrita para desarrolladores que usan Cursor, VS Code y GitHub Copilot — con configuraciones JSON listas para copiar y pegar y un paso de verificación funcional para cada uno.
La automatización de WhatsApp antes requería código personalizado — clientes REST, manejadores de webhook, gestión de sesiones y lógica de actualización de tokens. whapi-mcp reemplaza todo eso con un comando en lenguaje natural a su agente de IA. Instale el servidor MCP una sola vez, pegue una configuración JSON y toda la biblioteca de herramientas de WhatsApp estará disponible para cualquier cliente compatible con MCP que ya utilice.
Qué es realmente MCP
MCP — Model Context Protocol — es un sistema de plugins para que los agentes de IA llamen a herramientas externas reales. Una interfaz, muchos clientes compatibles: ejecute un servidor MCP y cada agente conectado puede usar sus herramientas sin integraciones separadas por cliente.
Sin MCP, su agente solo puede sugerir acciones. Con MCP, las ejecuta — llama a una API, lee un hilo de mensajes, envía una respuesta, confirma la entrega. La brecha entre sugerencia y automatización es el acceso a las herramientas.
Qué le Ofrece whapi-mcp
whapi-mcp es un servidor MCP desarrollado por Whapi.Cloud que envuelve la API REST de Whapi y la expone como herramientas estructuradas a cualquier agente de IA compatible con MCP. Generado automáticamente a partir de la especificación OpenAPI de Whapi, las herramientas cubren mensajes, grupos, canales, contactos, medios, etiquetas y más — 165 en total.
Funciona en Cursor, VS Code Agent Mode, GitHub Copilot Chat, Windsurf y Claude Desktop. Los cinco clientes usan el mismo paquete npm @whapi-cloud/whapi-mcp. Solo la ruta del archivo de configuración difiere entre ellos.
A diferencia de los puentes basados en QR, whapi-mcp se conecta a través de la infraestructura de producción de Whapi — sin archivos de sesión locales, sin reescaneos tras caídas de red, sin reconexiones a medianoche. La estabilidad se gestiona en la nube, no en su máquina de desarrollo.
| Característica | whapi-mcp (Whapi.Cloud) | Puente QR (sesión local) |
|---|---|---|
| Estabilidad de sesión | Estable en producción, gestionado en la nube | Se cae ante interrupciones de red; requiere reescaneo QR |
| Tiempo de configuración | Menos de 10 minutos (un comando npx) | 30 -- 60 min (servidor local + escaneo QR + configuración de puertos) |
| Soporte multi-número | Sí -- múltiples canales por cuenta | Típicamente un número por instancia de servidor |
| Cobertura de herramientas MCP | 165 herramientas estructuradas desde la especificación OpenAPI | Variable; a menudo requiere wrappers personalizados |
| API de Grupos y Canales | Acceso completo | Parcial o poco fiable |
Antes de Comenzar
Verifique estos requisitos previos antes de ejecutar cualquier comando de instalación:
-
Node.js 18 o posterior — necesario para ejecutar
npx. Verifique connode -ven su terminal. -
Token de API de Whapi — regístrese en whapi.cloud, conecte un número de WhatsApp y copie el token desde la configuración de su canal en el panel de Whapi.
-
IDE compatible con MCP — Cursor (cualquier versión reciente), VS Code con Agent Mode activado, o GitHub Copilot Chat en VS Code 1.99+ con un plan Copilot habilitado.
Conecta WhatsApp MCP en 10 Minutos
Cursor, VS Code y GitHub Copilot usan el mismo paquete @whapi-cloud/whapi-mcp — solo la ruta del archivo de configuración difiere. Instale el paquete una vez mediante npx; configúrelo una vez por IDE.
Paso 1 — Ejecute el Servidor una Vez para Verificar
Antes de configurar cualquier IDE, ejecute esto en su terminal para confirmar que el paquete se resuelve y el token es válido:
npx -y @whapi-cloud/whapi-mcp --api-token YOUR_WHAPI_TOKENReemplace YOUR_WHAPI_TOKEN con su token real. Si el servidor MCP arranca sin errores — el token funciona. No se necesita instalación global de npm; la configuración del IDE ejecuta npx automáticamente al inicio.
Paso 2 — Configure su IDE
Cada IDE lee la configuración del servidor MCP desde un archivo JSON específico. La estructura interna es casi idéntica en los tres clientes — solo la clave externa y la ubicación del archivo difieren.
Cursor
Cree o edite ~/.cursor/mcp.json para una configuración global (aplica a todos los proyectos), o .cursor/mcp.json dentro de la raíz de su proyecto para una configuración de alcance de proyecto:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Guarde, reinicie Cursor y abra el panel del agente — las herramientas de whapi aparecerán en la lista de herramientas disponibles.
VS Code (Modo Agente)
Cree .vscode/mcp.json en la raíz de su workspace. VS Code Agent Mode lee este archivo automáticamente. Tenga en cuenta la clave "type": "stdio" — requerida por el esquema de configuración MCP de VS Code:
{
"servers": {
"whapi": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Active el Agent Mode en la configuración de VS Code si aún no está activo. El servidor whapi se iniciará cuando abra el panel del agente.
GitHub Copilot (VS Code)
Para GitHub Copilot Chat en VS Code, agregue la entrada MCP a su settings.json de nivel de usuario, o cree .github/copilot/mcp.json en la raíz del proyecto. El soporte MCP requiere VS Code 1.99+ y un plan Copilot habilitado:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Abra Copilot Chat en modo Agent después de guardar — las herramientas de whapi aparecen en el selector de herramientas.
Claude Desktop
Si también usa Claude Desktop, la configuración va en claude_desktop_config.json. La estructura es idéntica a la de Cursor:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "YOUR_WHAPI_TOKEN"]
}
}
}Paso 3 — Asegure su Token
Nunca pegue el token de API de Whapi en un archivo de configuración que confirme en el control de versiones. En su lugar, haga referencia a una variable de entorno — la mayoría de los clientes MCP admiten una clave "env" en la configuración del servidor:
{
"mcpServers": {
"whapi": {
"command": "npx",
"args": ["-y", "@whapi-cloud/whapi-mcp", "--api-token", "${WHAPI_TOKEN}"]
}
}
}Establezca WHAPI_TOKEN en el entorno de su sistema o en un archivo .env excluido de git. Agregue el archivo de configuración a .gitignore si contiene un token sin cifrar. Los ejemplos completos están en la guía de configuración de Whapi MCP.
Verifique su Conexión
Después de reiniciar el IDE, abra su agente de IA y ejecute:
List my WhatsApp chatsUna conexión funcional devuelve sus chats recientes con sus Chat IDs. Si aparecen — la configuración está lista. Su agente de IA ahora tiene acceso directo a WhatsApp.
Los errores del servidor MCP casi siempre se deben a dos errores: ruta de archivo de configuración incorrecta o comas finales en el JSON. Ambos causan fallos de análisis silenciosos.
Qué Puede Hacer — 6 Casos de Uso Reales
Conecte MCP una vez; su agente de IA envía mensajes, gestiona grupos y lee chats con un simple prompt en lenguaje natural. Seis operaciones que funcionan sin configuración adicional tras la instalación:
-
"Envía un mensaje a Juan diciéndole que su pedido está listo" — el agente llama a
sendMessageTextcon el Chat ID de Juan y el cuerpo del mensaje. -
"Crea un grupo de WhatsApp llamado Sprint Team y agrega estos 5 números" — llama a
createGrouppara crear el grupo y luegoaddGroupParticipantcon el array de participantes. -
"Lee los últimos 20 mensajes del chat de soporte" — llama a
getMessagescon el chat ID y el recuento. Devuelve el hilo completo. -
"Envía el invoice.pdf al cliente por WhatsApp" — llama a
sendMessageDocumentcon la referencia del archivo y el Chat ID del destinatario. -
"Lista todos los chats no leídos y resume sus temas" — llama a
getChatspara la lista de chats y luegogetMessagespor cada chat — la IA extrae y resume el contexto. -
"Publica una actualización del producto en nuestro canal de WhatsApp" — llama a
sendMessageTextcon el Chat IDCHANNELID@newsletterdel canal como destinatario.
Cada prompt se corresponde con una llamada de herramienta. El agente selecciona la herramienta, completa los parámetros y devuelve el resultado — sin código de integración que escribir o mantener.
Whapi Agent Skill — Elimine los Errores de Formato
Los agentes de IA alucinan Chat IDs de WhatsApp. Sin conocimiento explícito del formato, el modelo inventa identificadores estructuralmente incorrectos — y la llamada de herramienta falla incluso cuando el agente selecciona la herramienta correcta.
WhatsApp usa tres formatos distintos de Chat ID que deben usarse de forma exacta:
-
[email protected]— contactos individuales (p. ej.,[email protected]) -
[email protected]— chats de grupo (p. ej.,[email protected]) -
CHANNELID@newsletter— Canales de WhatsApp (p. ej.,120363123456789012@newsletter)
El Whapi Agent Skill es un archivo de conocimiento descargable para Cursor y VS Code. Instálelo una vez — el agente cargará las reglas de formato de Chat ID y los patrones de uso en su contexto antes de cada sesión. La tasa de éxito en el primer intento mejora; la depuración de Chat IDs se reduce a casi cero.
Las instrucciones de instalación están en la guía de Whapi Agent Skills. Use whapi-mcp y el Agent Skill juntos — están diseñados para ello.
Solución Rápida de Problemas
Tres problemas que causan la mayoría de las instalaciones fallidas:
-
Servidor MCP no encontrado tras reiniciar el IDE — el archivo de configuración está en la ruta incorrecta o tiene un error de sintaxis JSON. La configuración global de Cursor se encuentra en
~/.cursor/mcp.json. VS Code lee.vscode/mcp.jsondesde la raíz del workspace. Valide su JSON con un linter — las comas finales causan fallos de análisis silenciosos. -
Error de autenticación o respuesta 401 — el token de API es inválido, ha expirado o fue pegado con espacios adicionales. Vuelva a copiarlo directamente desde la configuración del canal en su panel de Whapi y reemplace el valor en su configuración.
-
npx no puede resolver el paquete — confirme que Node.js 18+ está instalado (
node -v). En redes corporativas o VPN, verifique que el acceso al registro npm no esté bloqueado. Pruebenpm install -g @whapi-cloud/whapi-mcpcomo alternativa y actualice el config para usar"command": "whapi-mcp".
Para casos edge y patrones de configuración adicionales, consulte la guía de configuración de Whapi MCP. El código fuente y los issues abiertos están en GitHub (Whapi-Cloud/whapi-mcp).
Obtenga su token de API y ejecute su primer comando de agente de WhatsApp en menos de 10 minutos. Si encuentra un caso edge no cubierto aquí, abra el chat de soporte en esta página — el equipo de Whapi responde rápidamente.
