WhatsApp MCP Server

Servidor MCP personalizado que conecta a Claude con WhatsApp vía Twilio (un proveedor oficial de Meta que ya tiene su propia app aprobada — vos nunca creas la tuya en developers.facebook.com). Probado y funcionando (handshake MCP, listado de herramientas, webhook de mensajes entrantes).

Herramientas incluidas

Herramienta	Qué hace
send_text_message	Envía un mensaje de texto
send_template_message	Envía una plantilla aprobada vía Twilio Content API (para iniciar chats fuera de la ventana de 24h, o con alguien que no ha hecho "join" en el Sandbox)
send_media_message	Envía imagen, documento, audio o video por URL
search_perfume_catalog	Busca en el catálogo de imágenes guardadas por nombre/palabra clave (ver abajo)
view_catalog_image	Muestra una imagen ya guardada permanentemente en el servidor
view_image_message	Descarga una imagen directo de Twilio por su MediaUrl (fallback, fuera del catálogo local)
get_recent_messages	Devuelve los mensajes entrantes recibidos por el webhook

Importante: ni Meta ni Twilio permiten "leer el historial de chats" con una simple consulta — los mensajes entrantes solo llegan en tiempo real vía webhook. Por eso este servidor descarga cada imagen apenas llega y la guarda permanentemente en disco (carpeta media/), junto con un registro en catalog.json.

Caso de uso: catálogo buscable de perfumes

Si un distribuidor manda fotos de productos con el precio en la descripción (caption), el servidor:

1. Recibe la imagen vía webhook.
2. La descarga y guarda para siempre en media/.
3. Intenta extraer el precio del texto automáticamente (reconoce ₡25000, $45, "30 dólares", etc.).
4. Queda indexada en catalog.json para búsqueda por palabra clave.

Luego, para encontrar un perfume basta con pedirle a Claude algo como "buscá si el distribuidor mandó el Good Girl" — usa search_perfume_catalog, y si hay coincidencia, view_catalog_image para mostrar la foto exacta.

Además, si configuras Google Sheets (Paso 2.5 abajo), cada imagen nueva agrega automáticamente una fila a una hoja de cálculo — sin que nadie tenga que hablar con Claude — para que quien lleve el negocio (ej. tu mamá) la tenga siempre actualizada y a la mano en su celular o computadora.

Limitación a tener clara: esto solo captura fotos que lleguen después de tener el webhook desplegado y funcionando. No hay forma de recuperar fotos de chats viejos vía API — si hay catálogo anterior importante, tocaría reenviarlo una vez al número conectado para que quede capturado.

Sobre el hosting: si despliegas en un servicio con almacenamiento efímero (por ejemplo, el plan gratuito de algunos PaaS borra el disco en cada redeploy), la carpeta media/ y catalog.json se perderían. Para un catálogo que debe durar meses, usa un servicio con disco persistente (Render con un "Persistent Disk", una VPS con disco propio, o adaptar store.js para subir a un bucket S3/R2 en vez de al disco local).

Paso 1 — Crear tu cuenta de Twilio y activar el Sandbox de WhatsApp

1. Ve a https://www.twilio.com/try-twilio y regístrate (correo + verificación de celular — es un sistema separado de Meta).
2. En la consola, ve a Messaging → Try it out → Send a WhatsApp message.
3. Ahí verás el número del Sandbox de Twilio y un código único para unirte (algo como join palabra-clave).
4. Manda ese código exacto por WhatsApp normal, desde tu celular, a ese número. Twilio te va a responder confirmando que quedaste conectado.
5. En el Dashboard principal de la consola, copia tu Account SID y tu Auth Token — los vas a necesitar en el Paso 2. Trátalos como contraseñas: nunca los compartas en un chat ni los subas a un repo público.

Nota importante sobre el Sandbox: solo funciona con números que ya hicieron "join", y esa sesión puede vencer si no hay actividad por un tiempo (hay que reenviar el código). Sirve perfecto para probar todo el sistema, pero no para producción real con el distribuidor — para eso, más adelante hay que pasar por la verificación de Meta Business Manager (documentos, no SMS) usando el mismo panel de Twilio.

Paso 2 — Configurar el proyecto

cd whatsapp-mcp-server
npm install
cp .env.example .env

Edita .env y coloca:

• TWILIO_ACCOUNT_SID y TWILIO_AUTH_TOKEN: los que copiaste en el Paso 1.
• TWILIO_WHATSAPP_NUMBER: el número del Sandbox en formato whatsapp:+14155238886 (o tu número de producción más adelante).

Paso 2.5 — Conectar Google Sheets (opcional, pero recomendado para el catálogo)

Esto permite que el servidor escriba cada imagen nueva directamente en un Google Sheet, usando una "cuenta de servicio" (una cuenta robot que Google crea para automatizaciones — no es tu cuenta personal de Gmail).

1. Crear un proyecto en Google Cloud: ve a https://console.cloud.google.com/ y crea un proyecto nuevo (o usa uno existente).
2. Activar la API de Sheets: en el buscador del panel, escribe "Google Sheets API" y dale a Habilitar.
3. Crear la cuenta de servicio: ve a "APIs y servicios" → "Credenciales" → "Crear credenciales" → "Cuenta de servicio". Ponle cualquier nombre (ej. catalogo-perfumes) y termina el asistente sin agregar roles adicionales.
4. Generar la clave: dentro de la cuenta de servicio recién creada, ve a la pestaña "Claves" → "Agregar clave" → "Crear clave nueva" → tipo JSON. Se descarga un archivo .json.
5. Abre ese archivo descargado y copia dos valores:
   • client_email → va en GOOGLE_SERVICE_ACCOUNT_EMAIL.
   • private_key → va en GOOGLE_PRIVATE_KEY (cópialo completo, tal cual viene, con los \n incluidos).
6. Crear el Google Sheet: crea una hoja de cálculo nueva en https://sheets.google.com (puede estar vacía, el servidor le crea la pestaña "Catalogo" automáticamente con encabezados la primera vez que escribe).
7. Compartir el Sheet con la cuenta de servicio: dale clic a "Compartir" en el Sheet y agrega el email de client_email (el mismo que copiaste en el paso 5) con permiso de Editor. Este paso es el que más se olvida — sin él, el servidor no podrá escribir.
8. Copiar el ID del Sheet: en la URL del Sheet, https://docs.google.com/spreadsheets/d/AQUI_VA_EL_ID/edit, copia esa parte y ponla en GOOGLE_SHEET_ID.

Si estas tres variables no están configuradas, el servidor sigue funcionando normal (guarda todo en catalog.json e imágenes como siempre) — simplemente no escribe en el Sheet, y deja un aviso en los logs.

Paso 3 — Desplegarlo públicamente

Claude (y Twilio) necesitan una URL pública HTTPS, así que no basta con correrlo en tu laptop. Opciones sencillas y gratuitas para empezar:

• Render.com (recomendado para empezar): crea un "Web Service" nuevo apuntando a tu repo, build command npm install, start command npm start, y agrega las variables de entorno del .env.
• Railway.app: similar a Render, muy simple.
• Un VPS propio con Node instalado + un proxy (nginx/Caddy) para HTTPS.

Una vez desplegado, tendrás dos URLs útiles:

• https://tu-servidor.com/mcp → esta es la que registras en Claude (Paso 5).
• https://tu-servidor.com/webhook → esta la registras en Twilio (Paso 4).

Paso 4 — Configurar el webhook en Twilio

1. Vuelve a Messaging → Try it out → Send a WhatsApp message en la consola de Twilio (pestaña "Sandbox Settings").
2. En el campo "When a message comes in", pega https://tu-servidor.com/webhook y deja el método en POST.
3. Guarda. A diferencia de Meta, Twilio no pide un paso de verificación aparte — el webhook queda activo de inmediato.
4. (Opcional, recomendado antes de producción real) pon TWILIO_VALIDATE_SIGNATURE=true en tu .env para que el servidor rechace cualquier request que no venga realmente de Twilio.

Paso 5 — Registrar el conector en Claude

1. En claude.ai ve a Settings → Connectors → Add custom connector.
2. Pega la URL https://tu-servidor.com/mcp.
3. Guarda. Claude debería listar las 7 herramientas descritas arriba.

Probarlo en local antes de desplegar

npm start
# En otra terminal:
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Si ves la lista de herramientas en la respuesta, el servidor está funcionando.

Limitaciones a tener en cuenta

• El Sandbox de Twilio es solo para pruebas: cada número tiene que mandar join <código> antes de poder escribir, y esa sesión puede vencer con el tiempo. No sirve para que el distribuidor mande fotos de forma normal y permanente.
• Para producción real (número propio, sin "join", sin límites) hace falta pasar por la verificación de Meta Business Manager vía el panel de Twilio — es un trámite de papelería (razón social, comprobante de domicilio) que puede tardar varios días, no un SMS instantáneo.
• Fuera de la ventana de 24h desde el último mensaje del usuario, solo puedes escribir usando send_template_message con una plantilla aprobada (Twilio Content API).
• Este servidor usa la API oficial (a través de Twilio como proveedor autorizado de Meta), así que respeta los Términos de Servicio de WhatsApp — a diferencia de librerías no oficiales tipo whatsapp-web.js, que simulan WhatsApp Web y arriesgan el baneo del número.