WhatsApp Claude MCP

Un potente bot de WhatsApp integrado con Claude AI mediante el Protocolo de Contexto de Modelo (MCP). Envía mensajes a tu bot de WhatsApp y recibe respuestas inteligentes impulsadas por Claude, con acceso a herramientas y APIs externas.

🌟 Características

• Integración con Claude AI: Usa Claude 3.5 Sonnet para conversaciones inteligentes

• Herramientas MCP: Sistema de herramientas extensible para que Claude interactúe con APIs externas

• Generador de chistes: Herramienta integrada que obtiene chistes aleatorios de una API externa

• Memoria de conversación: Mantiene el contexto a lo largo de múltiples mensajes por usuario

• Webhook de WhatsApp: API REST sencilla para integrarse con WhatsApp

• Despliegue fácil: Funciona con el servidor Express, listo para despliegue en nube

Related MCP server: WAHA WhatsApp MCP Server

📋 Requisitos previos

• Node.js 18+

• npm o yarn

• Clave de API de Anthropic (obtenerla en console.anthropic.com)

• Acceso a la API de WhatsApp Cloud (para integración en producción)

🚀 Inicio rápido

1. Clonar e instalar

git clone https://github.com/yulianheroes-lgtm/whatsapp-claude-mcp.git
cd whatsapp-claude-mcp
npm install

2. Configurar las variables de entorno

cp .env.example .env

Edita el archivo .env y añade tu clave de API de Anthropic:

ANTHROPIC_API_KEY=your_anthropic_api_key_here
PORT=3000

3. Iniciar el servidor

npm start

Deberías ver:

✅ WhatsApp Claude MCP Server running on http://localhost:3000
🤖 Ready to process WhatsApp messages!

📡 Uso de la API

Comprobación de salud

curl http://localhost:3000/health

Enviar mensaje a Claude

curl -X POST http://localhost:3000/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1234567890",
    "message": "Tell me a joke"
  }'

Respuesta:

{
  "success": true,
  "userId": "1234567890",
  "message": "😂 Here's a programming joke for you!\n\nWhy do programmers prefer dark mode?\n\nBecause light attracts bugs! 🐛"
}

Limpiar el historial de conversación

curl -X POST http://localhost:3000/webhook/clear-history \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1234567890"
  }'

🛠️ Herramientas disponibles

Generador de chistes

Claude puede usar esta herramienta automáticamente cuando sea apropiado:

• Activación: Cuando el usuario pide chistes

• Tipos: aleatorios, de programación, generales

• API: Official Joke API

Ejemplo de interacción:

User: Tell me a funny programming joke
Bot: [Uses joke_generator tool] 😂 Here's a programming joke...

📁 Estructura del proyecto

whatsapp-claude-mcp/
├── src/
│   ├── index.js              # Main Express server
│   ├── whatsapp-handler.js   # Message handling & Claude integration
│   ├── mcp-server.js         # MCP tool definitions & execution
│   └── tools/
│       └── joke-generator.js # Joke generator tool implementation
├── .env.example              # Environment variables template
├── .gitignore               # Git ignore rules
├── package.json             # Dependencies
└── README.md                # This file

🔌 Integración con WhatsApp

Opción 1: API de WhatsApp Cloud

Para producción, intégrala con la API de WhatsApp Cloud:

1. Configura un webhook en Meta Business Platform

2. Apunta la URL del webhook a: https://your-domain.com/webhook/whatsapp

3. Cuando WhatsApp envíe mensajes, reenvíalos a este endpoint

Opción 2: Prueba local

Utiliza herramientas como curl, Postman o un script de prueba para enviar mensajes:

// test.js
const userId = '1234567890';
const message = 'Tell me a joke';

const response = await fetch('http://localhost:3000/webhook/whatsapp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId, message })
});

const result = await response.json();
console.log(result.message);

🧠 Cómo funciona

1. Recibir mensaje → El webhook de WhatsApp recibe un mensaje

2. Procesamiento con Claude → El mensaje se envía a Claude con las herramientas disponibles

3. Selección de herramienta → Claude decide si necesita herramientas

4. Ejecución de herramienta → El servidor MCP ejecuta las herramientas (p. ej., obtener chistes)

5. Generación de respuesta → Claude genera una respuesta usando los resultados de las herramientas

6. Enviar mensaje → La respuesta se envía de vuelta por WhatsApp

🚀 Añadir más herramientas

Para añadir una nueva herramienta (por ejemplo, clima, traducciones):

1. Crear el archivo de la herramienta

// src/tools/weather.js
export const weatherTool = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' }
    }
  }
};

export async function executeWeather(location) {
  // Fetch weather data
  return { /* weather data */ };
}

2. Regístrala en el servidor MCP

// src/mcp-server.js
import { weatherTool, executeWeather } from './tools/weather.js';

export class MCPServer {
  constructor() {
    this.tools = [
      jokeGeneratorTool,
      weatherTool  // Add here
    ];
  }

  async processTool(toolName, toolInput) {
    switch (toolName) {
      case 'get_weather':
        return await executeWeather(toolInput.location);
      // ...
    }
  }
}

📚 Referencia de la API

POST /webhook/whatsapp

Mensaje de la petición:

{
  "userId": "string (required)",
  "message": "string (required)"
}

Respuesta:

{
  "success": boolean,
  "userId": "string",
  "message": "string"
}

POST /webhook/clear-history

Mensaje de la petición:

{
  "userId": "string (required)"
}

Respuesta:

{
  "success": boolean,
  "message": "string"
}

🔐 Consideraciones de seguridad

• Claves de API: Nunca confirmes el archivo .enven el control de versiones

• Límite de peticiones: Considera añadir límites de velocidad para producción

• Validación de entrada: Valida siempre las cargas útiles del webhook

• HTTPS: Usa HTTPS en producción

• Autenticación: Añade verificación de firma de webhook para la integración con la API de WhatsApp

📝 Variables de entorno

🤝 Contribuciones

¡Siéntete libre de hacer fork, modificar y hacer tus aportaciones!

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más información.

🆘 Solución de problemas

"API key no encontrada"

• Asegúrate de que el archivo .env exista y contenga ANTHROPIC_API_KEY.

• Comprueba que la clave es válida en console.anthropic.com.

"Error al ejecutar la herramienta"

• Comprueba que las APIs externas sean accesibles

• Verifica la conectividad de red

• Revisa los registros de errores en la consola

"No se recibe respuesta de Claude"

• Comprueba que ANTHROPIC_API_KEY es correcta

• Asegúrate de que el modelo Claude está disponible

• Revisa los límites de peticiones de la API

📞 Soporte

Para problemas o preguntas:

1. Consulta la sección de solución de problemas

2. Revisa la documentación de la API de Claude

3. Abre una "issue" en GitHub

🎯 Mejoras futuras

• Soporte para imágenes y elementos multimedia en mensajes de WhatsApp

• Herramientas adicionales (clima, noticias, traducciones)

• Base de datos para historial de conversación persistente

• Límites de peticiones y autenticación

• Panel de administración para monitorización

• Soporte multilingüe

• Prompts del sistema personalizados para cada usuario

Hecho con ❤️ por yulianheroes-lgtm