Whatsapp MCP

WhatsApp MCP Skill

Este skill permite enviar mensajes, archivos y gestionar grupos de WhatsApp desde GitHub Copilot usando el servidor MCP whatsapp-mcp-server (basado en whatsapp-web.js).

Paso 0 — Verificar si el MCP está disponible

Antes de cualquier operación, ejecuta healthcheck_whatsapp. Interpreta el resultado:

Flujo principal

Enviar mensaje de texto

1. Buscar contacto: find_whatsapp_contact con nombre o número
2. Usar el id que termina en @c.us como chatId/phoneNumber
3. Siempre hacer dryRun: true primero para que el usuario confirme
4. Con confirmación: enviar con dryRun: false

Enviar archivo (PDF, imagen, VCF, etc.)

1. Verificar que el archivo existe en disco (ruta absoluta)
2. Si hay que convertir HTML→PDF: usar Chrome headless:

   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
     --headless=new --disable-gpu --no-sandbox \
     --print-to-pdf="/ruta/output.pdf" --print-to-pdf-no-header \
     "file:///ruta/input.html"
   

3. dryRun: true → confirmar → send_media_message con dryRun: false

Grupos

• Listar grupos: list_whatsapp_groups
• Añadir miembro: add_group_participant (necesita número normalizado)
• Eliminar miembro: remove_group_participant
• Link de invitación: get_group_invite_link

Historial de chat

• get_chat_messages con chatId y limit (máx 100)
• ⚠️ Los mensajes contienen datos personales (números de teléfono, texto de conversaciones). No almacenar ni exponer más allá de lo necesario para la operación actual.

Normalización de números de teléfono

El MCP normaliza automáticamente los números antes de usarlos. Formato interno: <dígitos>@c.us.

Reglas de normalización (normalizePhoneToWaId):

1. Se eliminan espacios, guiones y paréntesis.
2. Se elimina el + inicial si existe.
3. Si empieza con 0 → número local (ej. Austria 069x) → se reemplaza el 0 por el DEFAULT_COUNTRY_CODE configurado (43 por defecto).
4. Si ya tiene un código de país diferente al configurado (ej. 34..., 1...) → no se modifica. Pasar tal cual.

⚠️ Error histórico: Antes de la corrección del 2025-06, el server añadía 43 a cualquier número no local, causando que números españoles 34619880445 → 4334619880445@c.us ❌. Esto está corregido en src/whatsapp/client.ts.

Reglas importantes

• Siempre dryRun primero antes de enviar — nunca enviar sin confirmación del usuario.
• Los chatId para contactos terminan en @c.us, para grupos en @g.us.
• Para números no austriacos (ej. españoles 34..., americanos 1...): pasar el número completo con código de país. El MCP lo detecta automáticamente y no le añade el 43.
• PDFs e imágenes: send_media_message acepta ruta absoluta en disco del servidor.
• Si el contacto no aparece: probar con apellido/nombre invertidos o variantes de mayúsculas.

Referencia de tools

Ver references/tools.md para descripción completa de cada tool MCP disponible.

Instalación del MCP

Si el MCP no está disponible, ver references/install.md para guiar al usuario paso a paso.