convez.ai
MCP ServerIntegração & APIsIntermediário
juanpablo-estrada

Wasapi MCP Server

juanpablo-estrada/wasapi-mcp-server

Controle WhatsApp Business direto do Claude com MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que integra sua conta WhatsApp Business com Claude e Cursor, permitindo gerenciar mensagens, contatos e conversas por linguagem natural. Oferece instalação simplificada via interface gráfica ou assistente de configuração automática.

Instalação

$npx convez-ai juanpablo-estrada/wasapi-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
14%
Último commit
há 3 meses
Versão
v1.1.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de campanhas e mensagens em massa via WhatsApp
  • Gestão de contatos e histórico de conversas integrado ao fluxo de trabalho
  • Consultas e respostas a mensagens usando IA sem sair do Claude

Veredito

Integração sólida e bem documentada entre WhatsApp Business e Claude. A instalação facilitada (incluindo opção sem terminal) reduz fricção, mas o servidor permanece em desenvolvimento comunitário — verifique limitações conhecidas antes de usar em produção.

README

A tradução para o português deste README ainda está na fila.

Wasapi MCP 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

Antes de empezar necesitas una API key de Wasapi. Consíguela en app.wasapi.io/account/developer.

Opción 1 — 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 2 — Asistente de configuración (recomendada para developers)

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

npx -y @jpabloe/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 @jpabloe/wasapi-mcp-server
wasapi-mcp setup --restart

Con la instalación global, el comando wasapi-mcp queda disponible en tu terminal de forma permanente.

Opción 3 — 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", "@jpabloe/wasapi-mcp-server"],
      "env": {
        "WASAPI_API_KEY": "tu_api_key_aquí",
        "WASAPI_FROM_ID": "12345"
      }
    }
  }
}
  1. Reinicia tu cliente MCP.

Rutas de configuración más comunes:

ClientemacOSLinuxWindows
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
Cursor~/.cursor/mcp.json~/.cursor/mcp.json%USERPROFILE%\.cursor\mcp.json

Tip: npx -y @jpabloe/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."

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


Clientes compatibles

Funciona con cualquier cliente MCP que ejecute servidores locales por stdio:

ClienteInstalaciónNotas
Claude Desktop.mcpb (Opción 1) o asistente (Opción 2)Recomendado
CursorAsistente (Opción 2) con auto-configuración y reinicio
Claude Codesetup --print-only + claude mcp add o editar ~/.claude.json
Windsurf, Zed y otrossetup --print-only + pegar el JSON en su configuración

Importante: este es un servidor MCP local (stdio). No funciona en Claude.ai web — eso requiere un servidor MCP hosteado, que es un modelo de despliegue distinto.


Referencia del asistente (setup)

npx -y @jpabloe/wasapi-mcp-server setup [flags]
FlagDescripción
--target claude-desktop|cursorSalta el menú de plataforma e instala directo en esa
--restartReinicia la aplicación destino automáticamente al terminar (solo macOS)
--print-onlyImprime el JSON personalizado; nunca escribe en disco
--local(desarrollo) Escribe la ruta local del repo en vez de npx

Ejemplos:

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

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

Variables de entorno

VariableRequeridaDescripción
WASAPI_API_KEYSíTu API key de Wasapi. Consíguela en app.wasapi.io/account/developer
WASAPI_FROM_IDNoID del número de WhatsApp por defecto para mensajes salientes. Descúbrelo con la herramienta list_whatsapp_numbers
WASAPI_BASE_URLNoSobrescribe la URL base del SDK (staging / pruebas)
WASAPI_DEBUGNoPonla en 1 para logs detallados de errores por stderr

Herramientas disponibles

51 herramientas en total.

Contactos (9)

HerramientaQué haceParámetros clave
list_contactsLista paginada de contactos con búsqueda opcionalsearch, labels[], page
get_contactObtiene un contacto por su WhatsApp IDwa_id
create_contactCrea un contactofirst_name (requerido), phone, country_code, last_name, email
update_contactActualiza un contacto existentewa_id + campos a cambiar
delete_contactElimina un contacto permanentementewa_id
add_label_to_contactAgrega una etiquetacontact_uuid, label_id
remove_label_from_contactQuita una etiquetacontact_uuid, label_id
assign_agent_to_contactAsigna un agente automáticamentecontact_uuid
export_contactsInicia una exportación de todos los contactosemail_urls[] (opcional)

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

WhatsApp — Mensajería y conversaciones (7)

HerramientaQué haceParámetros clave
list_whatsapp_numbersLista los números conectados y sus from_id—
send_messageEnvía un mensaje de textowa_id, message, from_id (opcional)
send_templateEnvía una plantilla aprobada, con variables y adjunto por URLrecipients[], template_id, contact_type, body_vars[], url_file, from_id (opcionales)
send_attachmentEnvía un archivo desde una ruta localwa_id, filePath, caption, filename, from_id (opcionales)
send_contact_cardEnvía tarjetas de contacto (vCard)wa_id, contacts[], from_id (opcional)
get_conversationObtiene el hilo de mensajes con un contactowa_id, from_id, page (opcionales)
change_conversation_statusCambia el estado de la conversaciónwa_id, status (open/hold/closed), agent_id (opcional)

WhatsApp — Plantillas (5)

HerramientaQué haceParámetros clave
list_whatsapp_templatesLista todas las plantillas de la cuenta—
get_whatsapp_templateDetalle de una plantillatemplate_uuid
get_template_fieldsVariables que acepta una plantilla (úsalo antes de send_template)template_uuid
list_templates_by_numberPlantillas disponibles para un númerofrom_id
sync_meta_templatesSincroniza plantillas desde Meta—

WhatsApp — Flows (6)

HerramientaQué haceParámetros clave
list_flowsLista los WhatsApp Flows de la cuenta—
list_flows_by_numberFlows disponibles para un númerofrom_id (opcional)
send_flowEnvía un Flow interactivo a un contactowa_id, message, cta, screen, flow_id
get_flow_responsesRespuestas que enviaron los usuarios por un Flowflow_id, page (opcional)
get_flow_assetsDetalle y assets de un Flowflow_id
get_flow_screensPantallas de un Flow (para elegir screen en send_flow)flow_id

Campañas (2)

HerramientaQué haceParámetros clave
list_campaignsLista las campañas de difusión de la cuenta—
get_campaignDetalle de una campaña con sus envíos por contactocampaign_uuid

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

Funnels (3)

HerramientaQué haceParámetros clave
list_funnelsLista los embudos de venta y sus etapas—
search_contact_in_funnelsBusca un contacto en los embudosphone_number o contact_uuid
move_contact_to_funnel_stageMueve un contacto a otra etapafunnel_contact_id, to_stage_id

Métricas (11)

HerramientaQué haceParámetros clave
get_online_agentsAgentes en línea—
get_status_contactsContactos por estado—
get_total_campaignsTotal de campañas en un rangostart_date, end_date
get_consolidated_conversationsConversaciones consolidadasstart_date, end_date
get_agent_conversationsConversaciones por agentestart_date, end_date
get_messagesVolumen de mensajesstart_date, end_date
get_messages_botMensajes del botstart_date, end_date
get_agent_time_responseTiempo de respuesta de un agenteagent_id, start_date, end_date
get_agent_transferredConversaciones transferidas de un agenteagent_id, start_date, end_date
get_agent_volume_of_workVolumen de trabajo de un agenteagent_id, start_date, end_date
get_agent_time_in_conversationTiempo en conversación de un agenteagent_id, start_date, end_date

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

Bot (1)

HerramientaQué haceParámetros clave
toggle_bot_statusActiva/desactiva el chatbot para un contactowa_id, action (enable/disable/disable_permanently), from_id (opcional)

Workflow (1)

HerramientaQué haceParámetros clave
get_workflow_statusesLista cambios de estado de conversaciones, con filtrosaction, phone, agent_id, dates, per_page, page (todos opcionales)

Campos personalizados (5)

HerramientaQué haceParámetros clave
list_custom_fieldsLista los campos personalizados—
get_custom_fieldObtiene un campo por IDfield_id
create_custom_fieldCrea un camponame
update_custom_fieldRenombra un campofield_id, name
delete_custom_fieldElimina un campofield_id

Usuario (1)

HerramientaQué haceParámetros clave
get_current_userDatos de la cuenta asociada a la API key—

¿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 @jpabloe/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 @jpabloe/wasapi-mcp-server@latest --version

Si lo instalaste globalmente

npm install -g @jpabloe/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: archivo no encontrado"

El filePath debe existir en la máquina donde corre el servidor MCP (tu computador), no en la del cliente. Los adjuntos por URL aún no están soportados por el SDK; descarga el archivo localmente primero.

"list_conversations no existe"

Correcto — el SDK aún no lo expone. Usa get_conversation con un wa_id conocido para traer el hilo de mensajes con ese contacto.

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.


Limitaciones conocidas

LimitaciónDetalle
list_conversations no implementadoEl SDK no lo expone. Usa get_conversation con un wa_id.
send_attachment requiere ruta localPara enviar archivos por URL usa send_template con url_file.
No funciona en Claude.ai webRequiere un servidor MCP hosteado (modelo de despliegue distinto).

Licencia

ISC

Ver o original no GitHub

Bom para

Relacionados