# Whatsapp MCP

> Send WhatsApp messages, files (PDF, images, VCF), and manage groups and contacts using the WhatsApp MCP server (whatsapp-web.js). Use this skill when the user wants to send a WhatsApp message, find a contact, list groups, send a document or image via WhatsApp, add/remove group members, or get chat history. Also use when the user asks how to install or configure the WhatsApp MCP. Triggers on: send WhatsApp, mensaje WhatsApp, mandar por WhatsApp, enviar archivo WhatsApp, grupo WhatsApp, contacto WhatsApp, instalar MCP WhatsApp.

- Skill: `lunasoft2001/whatsapp-mcp` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lunasoft2001/whatsapp-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lunasoft2001/whatsapp-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: lunasoft2001 (https://skillmd.com/u/lunasoft2001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lunasoft2001/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:

| Resultado | Acción |
|---|---|
| `"whatsapp": "ready"` | Continúa normalmente |
| `"whatsapp": "initializing"` | Espera 5-10 segundos y reintenta |
| Error / tool no disponible | Guía al usuario con [references/install.md](references/install.md) |

## 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:
   ```bash
   /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`.

| Formato de entrada | Resultado | Caso de uso |
|---|---|---|
| `+34619880445` | `34619880445@c.us` | Número español con `+` |
| `34619880445` | `34619880445@c.us` | Número español sin `+` |
| `069912294428` | `4369912294428@c.us` | Número local austriaco (comienza con `0`) |
| `43699123456` | `43699123456@c.us` | Número austriaco completo |
| `16505551234` | `16505551234@c.us` | Número USA |

**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](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](references/install.md) para guiar al usuario paso a paso.