WhatsApp MCP Server

Conecta tu WhatsApp a Claude Desktop. Todo permanece en tu máquina — sin nube, sin servidores

Documentación

WhatsApp MCP — Local

Conecta tu WhatsApp a Claude Desktop. Todo permanece en tu máquina — sin nube, sin servidores, el desarrollador no ve nada.

📦 Todos los mensajes se almacenan en una base de datos SQLite local (~/.whatsapp-mcp/whatsapp.db)
🔒 Las claves de autenticación se guardan solo en ~/.whatsapp-mcp/session/ — nunca salen de tu máquina
🔍 Búsqueda de texto completo en todo el historial de chats
📥 Importa chats antiguos con la función Exportar Chat de WhatsApp

Requisitos previos

Node.js v20+ — descárgalo de nodejs.org (versión LTS)
Claude Desktop — descárgalo de claude.ai/download
Git — descárgalo de git-scm.com

Configuración (máquina nueva)

Windows — instalador con doble clic

Instala Node.js LTS si no lo tienes
git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
Abre la carpeta clonada → haz doble clic en install.bat

Eso es todo. El archivo por lotes se encarga de npm install y la configuración automáticamente. Sin PowerShell, sin edición manual.

Mac / Linux — terminal

git clone https://github.com/khetsinghrajput/WhatsApp-MCP-Local.git
cd WhatsApp-MCP-Local
make install

¿No tienes make? Usa: chmod +x install.sh && ./install.sh

Manual (cualquier plataforma)

npm install
npm run setup

¿Error de PowerShell en Windows? Si ves "la ejecución de scripts está deshabilitada", ejecuta esto una vez en PowerShell y vuelve a intentarlo:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
O simplemente usa install.bat en su lugar — usa cmd.exe que nunca tiene este problema.

La salida se ve así:

✅ Done! Config written:
   Server  : whatsapp
   Command : C:\Program Files\nodejs\node.exe
   Script  : C:\Users\You\WhatsApp-MCP-Local\src\index.ts

📋 Next steps:
   1. Fully quit Claude Desktop (system tray → Quit)
   2. Reopen Claude Desktop
   3. Your browser opens at http://localhost:3000 — scan the QR with WhatsApp
   4. Done! Use whatsapp_status in Claude to confirm.

Después de la configuración

Cierra y vuelve a abrir Claude Desktop
El navegador se abre automáticamente en http://localhost:3000 — escanea el código QR
Espera unos minutos para que el historial se sincronice

Revisa el progreso en Claude:

whatsapp_status
→ 📦 1,240 messages stored across 108 chats
→ 📅 History goes back to: 25/05/2025

Herramientas disponibles

Herramienta	Qué hace
`whatsapp_status`	Estado de la conexión + estadísticas de la base de datos
`whatsapp_list_chats`	Todos los chats ordenados por más reciente
`whatsapp_list_groups`	Solo chats de grupo
`whatsapp_find_contact`	Busca contactos por nombre o número de teléfono
`whatsapp_get_messages`	Lee mensajes de un chat (historial completo)
`whatsapp_send_message`	Envía un mensaje
`whatsapp_search_messages`	Búsqueda de texto completo en todos los mensajes

Importar chats antiguos

WhatsApp solo envía el historial reciente durante la sincronización inicial. Para obtener mensajes más antiguos:

Paso 1 — Exportar desde tu teléfono

Abre el chat en WhatsApp
Toca ⋮ → Más → Exportar Chat
Elige Sin medios
Envía el archivo .txt a tu computadora

Paso 2 — Ejecuta el importador

Primero encuentra el JID del contacto usando whatsapp_find_contact "Their Name" en Claude, luego:

npm run import -- "C:/path/to/WhatsApp Chat with John Doe.txt" "923001234567@s.whatsapp.net" "John Doe"

El importador muestra:

✅ Import complete!
   Contact  : John Doe
   Messages : 1,847 imported
   Range    : 15/03/2023 → 17/05/2026

📦 Database now has 3,091 messages across 109 chats

Los mensajes se deduplican automáticamente — es seguro ejecutarlo varias veces.

Tus datos

~/.whatsapp-mcp/
  session/          ← WhatsApp auth keys (never shared)
    creds.json
    pre-key-*.json
  whatsapp.db       ← All messages, searchable forever

Para desvincular de WhatsApp: Teléfono → Configuración → Dispositivos vinculados → busca WhatsApp MCP → Cerrar sesión. Luego elimina ~/.whatsapp-mcp/session/ y reinicia Claude Desktop — obtendrás un nuevo código QR.

Para eliminar por completo: Borra ~/.whatsapp-mcp/ y elimina el bloque mcpServers de la configuración.

Solución de problemas

Error de "Servidor desconectado" en Windows: Asegúrate de haber usado tsx.cmd (no tsx) en la configuración y que las rutas usen / en lugar de \.

El navegador no se abre automáticamente: Visita http://localhost:3000 manualmente.

Los chats se muestran como números en lugar de nombres: Es normal en la primera conexión — los nombres se cargan a medida que WhatsApp sincroniza los contactos. Espera 30 segundos y revisa de nuevo.

No se encuentra el contacto: Usa whatsapp_find_contact "name" — si muestra "aún no hay mensajes sincronizados", exporta el chat y usa el importador.