📱 WhatsApp MCP — Servidor remoto HTTP/SSE

Servidor del Protocolo de Contexto de Modelo (MCP) para WhatsApp, construido con whatsapp-web.js y TypeScript. Admite tanto el modo stdio local (Claude Desktop) como el modo remoto HTTP/SSE (Claude.ai Remote MCP).

⚠️ Términos de servicio de WhatsApp — IMPORTANTE

Lea esto antes de usar este proyecto.

Los Términos de servicio y la Política de uso aceptable de WhatsApp prohíben el uso de herramientas de automatización no oficiales en cuentas personales o comerciales.

🚫 Acciones que provocarán que su número sea BANEADO:

✅ Prácticas más seguras:

• Utilice un número de teléfono dedicado/de prueba, no su número personal

• Solo envíe mensajes a contactos que hayan dado su consentimiento

• Mantenga la frecuencia de mensajes baja y similar a la humana

• No exponga sus endpoints /sse o REST públicamente sin protección API_KEY

• No utilice esto para marketing, envíos masivos de ventas o cualquier mensajería comercial a gran escala

• Utilice la API de WhatsApp Business (Oficial) para uso comercial o de producción

🔒 Este proyecto está destinado únicamente a la automatización personal y al desarrollo/pruebas. El autor no se hace responsable de ningún baneo de cuenta o consecuencia legal resultante del mal uso.

Related MCP server: WhatsApp MCP Server

🗂️ Estructura del proyecto

whatsapp-mcp/
├── src/
│   ├── index.ts          # stdio MCP server (Claude Desktop)
│   ├── remote.ts         # HTTP/SSE MCP server (Remote MCP + REST API)
│   └── send_message.ts   # CLI script to send a single message
├── dist/                 # Compiled JavaScript (auto-generated, do not edit)
├── .wwebjs_auth/         # WhatsApp session data (⚠️ keep this gitignored!)
├── .wwebjs_cache/        # Puppeteer browser cache (gitignored)
├── package.json
├── tsconfig.json
├── render.yaml           # Render.com deployment config
├── start-remote.bat      # Windows quick-start script
└── README.md

🚀 Inicio rápido

Requisitos previos

• Node.js v18+ y npm

• Una cuenta de WhatsApp (¡use un número de prueba!)

• Google Chrome o Chromium instalado (utilizado internamente por Puppeteer)

1. Instalar dependencias

npm install

2. Compilar TypeScript

npm run build

3. Iniciar el servidor

Modo remoto HTTP/SSE (Claude.ai Remote MCP):

npm run start:remote

Modo de desarrollo (no requiere compilación, usa ts-node):

npm run dev:remote

Modo stdio (Claude Desktop):

npm start

4. Escanear el código QR

Abra su navegador y vaya a:

http://localhost:3000/qr

Escanee el código QR con WhatsApp → Dispositivos vinculados → Vincular un dispositivo.

🔌 Endpoints de la API

🛠️ Herramientas MCP disponibles

🔐 Opcional: Autenticación con Bearer Token

Proteja sus endpoints REST configurando una variable de entorno API_KEY:

API_KEY=mysecretkey npm run start:remote

Incluya el token en todas las solicitudes:

curl -H "Authorization: Bearer mysecretkey" http://localhost:3000/tools/status

🌐 Pruebas con ngrok (HTTPS público)

1. Instale ngrok

2. Inicie su servidor: npm run start:remote

3. En una terminal nueva: ngrok http 3000

4. Copie la URL generada (ej. https://xxxx.ngrok-free.app)

En Claude.ai → Configuración → Integraciones → Remote MCP, pegue:

https://xxxx.ngrok-free.app/sse

☁️ Desplegar en Render

1. Envíe este repositorio a GitHub (consulte los pasos de Git a continuación)

2. Vaya a render.com → New → Web Service

3. Conecte su repositorio de GitHub

4. Configure:

   • Comando de compilación: npm install && npm run build

   • Comando de inicio: npm run start:remote

   • Entorno: NODE_ENV=production

   • Opcional: API_KEY=yoursecretkey

5. Despliegue y copie su URL https://your-app.onrender.com

Péguelo en Claude Remote MCP:

https://your-app.onrender.com/sse

⚠️ Nota: Los datos de la sesión de WhatsApp (.wwebjs_auth) no persisten entre despliegues de Render. Utilice un Render Disk o vuelva a escanear el código QR después de cada despliegue.

📦 Scripts de npm

📄 Recomendaciones para .gitignore

Asegúrese de que su .gitignore incluya:

node_modules/
dist/
.wwebjs_auth/
.wwebjs_cache/
.env
*.bat

🔒 Nunca suba .wwebjs_auth/ — contiene las credenciales de su sesión de WhatsApp.

🔧 Variables de entorno

🤝 Contribuciones

¡Las solicitudes de extracción (pull requests) son bienvenidas! Para cambios importantes, abra primero un issue.

📜 Licencia

MIT — utilícelo de forma responsable y de acuerdo con los Términos de servicio de WhatsApp.

💡 Consejo: Instale la extensión GitLens en VS Code para una experiencia de Git mucho más rica: historial de confirmaciones, blame, comparaciones y más.