Wasapi Server

npm version license node

Servidor MCP para Wasapi. Gestiona tu cuenta de WhatsApp Business directamente desde Claude, Cursor o cualquier cliente compatible con MCP: envía mensajes, administra contactos y consulta conversaciones usando lenguaje natural.

Tabla de contenidos

• Instalación
  • Opción 1 — Conector remoto (recomendado · Claude.ai web, ChatGPT, etc.)
  • Opción 2 — Claude Desktop, sin terminal
  • Opción 3 — Asistente de configuración (recomendada para developers)
  • Opción 4 — Configuración manual
• ¿Qué puedo hacer?
• Clientes compatibles
• Referencia del asistente (setup)
• Variables de entorno
• Herramientas disponibles
• ¿Cómo actualizo?
• Solución de problemas
• Privacidad
• Limitaciones conocidas

Instalación

Opción 1 — Conector remoto (recomendado · Claude.ai web, ChatGPT, etc.)

La forma más fácil y recomendada. No requiere instalación: cualquier IA que soporte conectores MCP remotos puede conectarse directamente con tu cuenta de Wasapi.

Endpoint: https://ia.wasapi.io/mcp

1. En tu cliente de IA (Claude.ai, ChatGPT, etc.), abre la sección de conectores o integraciones.
2. Agrega un nuevo conector MCP con la URL: https://ia.wasapi.io/mcp
3. El cliente abrirá el flujo de autorización de Wasapi — inicia sesión con tu cuenta.
4. Acepta los permisos en la pantalla de consentimiento.
5. ¡Listo! La IA ya puede gestionar tu cuenta de WhatsApp Business.

Para una guía detallada con capturas de pantalla, visita: ayuda.wasapi.io — Conecta Claude, ChatGPT y otras IA con el MCP de Wasapi

Las opciones 2–4 son para instalar el servidor MCP localmente (necesario si usas clientes de escritorio como Claude Desktop o Cursor). Antes de empezar necesitas una API key de Wasapi. Consíguela en app.wasapi.io/account/developer.

Opción 2 — Claude Desktop, sin terminal

La forma más fácil si usas Claude Desktop y no quieres tocar la terminal:

1. Descarga wasapi-mcp.mcpb (enlace directo, siempre la última versión).
2. Haz doble click en el archivo — Claude Desktop abre el diálogo de instalación.
3. Pega tu API key de Wasapi.
4. Haz click en Instalar.
5. Activa la extensión: ve a Configuración → Extensiones, busca "Wasapi" y enciéndela (Claude Desktop instala deshabilitadas las extensiones de desarrolladores no verificados).
6. Abre un chat nuevo y prueba: "Lista mis números de WhatsApp".

Nota: verás un aviso de que el desarrollador "no está verificado por Anthropic". Es lo esperado para extensiones distribuidas fuera del directorio oficial de Anthropic; la fuente es este repositorio.

Opción 3 — Asistente de configuración (recomendada para developers)

No necesitas instalar nada previamente — npx descarga y ejecuta el paquete en un solo paso:

npx -y @wasapi/mcp-server setup --restart

El asistente te guía por todo el proceso:

1. Abre tu navegador en el panel de Wasapi para que copies tu API key
2. Valida la key contra el API en vivo
3. Selecciona un número de WhatsApp por defecto (si tienes alguno)
4. Detecta tu cliente MCP (Claude Desktop / Cursor) y escribe la configuración
5. Reinicia la aplicación por ti (con el flag --restart)

npm install -g @wasapi/mcp-server
wasapi-mcp setup --restart

Opción 4 — Configuración manual

Si prefieres editar la configuración tú mismo:

1. Consigue tu API key en app.wasapi.io/account/developer
2. Agrega este bloque a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "wasapi": {
      "command": "npx",
      "args": ["-y", "@wasapi/mcp-server"],
      "env": {
        "WASAPI_API_KEY": "tu_api_key_aquí",
        "WASAPI_FROM_ID": "12345"
      }
    }
  }
}

3. Reinicia tu cliente MCP.

Rutas de configuración más comunes:

Tip: npx -y @wasapi/mcp-server setup --print-only genera este JSON ya personalizado con tu cuenta, sin escribir ningún archivo.

¿Qué puedo hacer?

Una vez instalado, háblale a tu cliente MCP en lenguaje natural. Algunos ejemplos:

"Lista los primeros 10 contactos de mi cuenta de Wasapi."

"¿Cuántos contactos tengo en total?"

"Crea un contacto: Ana Gómez, teléfono +57 300 123 4567, código de país 57."

"Envíale por WhatsApp a +57 300 123 4567 el mensaje: 'Hola Ana, te confirmo tu cita mañana a las 10am.'"

"Etiqueta al contacto con UUID abc-123 con el label 42."

"Muéstrame los últimos mensajes con el wa_id 573001234567."

"Envíale la plantilla de bienvenida al 573001234567 con el nombre Ana en la variable 1."

"¿Qué flows tengo configurados? Envíale el flow de encuesta al 573001234567."

"¿Cómo le fue a mi última campaña? ¿Cuántos mensajes se entregaron?"

"¿Cuántos mensajes enviamos entre el 1 y el 31 de enero? ¿Y cuántos agentes están en línea ahora?"

"Desactiva el bot para el contacto 573001234567 y dime qué campos personalizados tengo configurados."

"Muéstrame las conversaciones abiertas sin etiqueta y dame el reporte de satisfacción del último mes."

Claude decide cuál de las 62 herramientas usar, pide aclaraciones si algo es ambiguo, y te muestra la respuesta.

Clientes compatibles

Referencia del asistente (setup)

npx -y @wasapi/mcp-server setup [flags]

Ejemplos:

# Configurar Claude Desktop y reiniciarlo automáticamente
npx -y @wasapi/mcp-server setup --target claude-desktop --restart

# Obtener el JSON para pegarlo manualmente en Windsurf / Zed / Claude Code
npx -y @wasapi/mcp-server setup --print-only

Variables de entorno

Herramientas disponibles

62 herramientas en total.

Contactos (9)

Los contactos se identifican por wa_id (un WhatsApp ID en texto), no por ID numérico.

WhatsApp — Mensajería y conversaciones (7)

WhatsApp — Plantillas (5)

WhatsApp — Flows (6)

Campañas (2)

Crear, editar o eliminar campañas aún no está disponible (el SDK no lo implementa todavía).

Funnels (3)

Métricas (11)

Las métricas con rango de fechas esperan formato YYYY-MM-DD.

Bot (1)

Workflow (1)

Campos personalizados (4)

Usuario (2)

Conversaciones (2)

Etiquetas (6)

Reportes (3)

¿Cómo actualizo?

Depende de cómo instalaste:

Si usaste el asistente o la configuración manual con npx

Tu configuración usa npx -y @wasapi/mcp-server sin versión fijada, así que basta con reiniciar tu cliente MCP (Cmd+Q completo + abrir) — npx resuelve la última versión automáticamente.

Si por caché te sigue sirviendo una versión vieja, fuérzala y reinicia:

npx -y @wasapi/mcp-server@latest --version

Si lo instalaste globalmente

npm install -g @wasapi/mcp-server@latest

y reinicia tu cliente.

Si instalaste la extensión .mcpb en Claude Desktop

Las extensiones instaladas fuera del directorio oficial de Anthropic no se actualizan solas:

1. Descarga el nuevo wasapi-mcp.mcpb (siempre apunta a la última versión)
2. Haz doble click — Claude Desktop detecta la extensión existente y la actualiza
3. Tu API key se conserva, pero tenla a mano por si el diálogo la vuelve a pedir
4. Verifica que la extensión siga activa en Configuración → Extensiones

Puedes ver qué versión tienes instalada en Configuración → Extensiones → Wasapi.

Solución de problemas

"Instalé la extensión pero Claude no ve las herramientas de Wasapi"

Las extensiones de desarrolladores no verificados se instalan deshabilitadas. Ve a Configuración → Extensiones, busca "Wasapi" y actívala. Luego abre un chat nuevo (los chats abiertos antes de activar no recargan las herramientas).

"Ejecuté el asistente pero el MCP no aparece en mi cliente"

1. Reinicio completo, no solo cerrar la ventana. En macOS: Cmd+Q, no la × roja. O usa el flag --restart.
2. Verifica la ruta de configuración. El asistente imprime la ruta donde escribió. Confirma que sea la misma que usa tu cliente (tabla de rutas arriba).
3. Revisa variables de entorno conflictivas que hayan quedado de pruebas anteriores:

   echo $CLAUDE_DESKTOP_CONFIG
   echo $CURSOR_MCP_CONFIG
   

   Si alguna imprime una ruta, elimínala (unset CLAUDE_DESKTOP_CONFIG) y vuelve a ejecutar el asistente. El asistente actual te advierte de esto, pero versiones anteriores no.

"Las herramientas devuelven 'API key inválida o sin permisos'"

Tu API key funciona pero no tiene permiso para ese endpoint. Revisa la consola de desarrollador en app.wasapi.io/account/developer y confirma que la key tiene los permisos que necesitas.

"send_attachment falla"

send_attachment espera una URL pública en file_url (no una ruta de archivo local). El tipo de medio se infiere de la extensión de la URL (.jpg/.png → imagen, .mp4 → video, .mp3 → audio; cualquier otra → documento). Asegúrate de que la URL sea accesible públicamente y termine con la extensión correcta.

Activar logs de depuración

WASAPI_DEBUG=1 wasapi-mcp

O agrega "WASAPI_DEBUG": "1" al bloque env de tu configuración MCP. Los logs salen por stderr.

Privacidad

• Conector remoto (ia.wasapi.io): las solicitudes pasan por el servidor MCP de Wasapi, que actúa como intermediario OAuth entre tu cliente de IA y la API de Wasapi. No almacena el contenido de tus mensajes ni contactos.
• Instalación local (stdio): el servidor MCP corre en tu máquina. Envía tus solicitudes únicamente a la API de Wasapi (https://api-ws.wasapi.io). No transmite datos a los autores del paquete ni a terceros.
• No recolecta, almacena ni comparte tus datos por su cuenta. Tu API key se guarda donde tu cliente MCP la configure (en Claude Desktop, en el keychain del sistema operativo).
• El tratamiento de los datos de tu cuenta por parte de Wasapi se rige por la Política de Privacidad de Wasapi.
• Soporte y contacto: issues del repositorio.

Limitaciones conocidas

Licencia

ISC