WhatsApp Claude MCP

Ein leistungsstarker WhatsApp-Bot, der mithilfe des Model Context Protocol (MCP) in Claude AI integriert ist. Sende Nachrichten an deinen WhatsApp-Bot und erhalte intelligente Antworten, unterstützt von Claude, mit Zugriff auf externe APIs und Tools.

🌟 Features

• Claude-AI-Integration: Nutzt Claude 3.5 Sonnet für intelligente Gespräche

• MCP-Tools: Erweiterbares Toolsystem für Claude, um mit externen APIs zu interagieren

• Witzgenerator: Integriertes Tool, das zufällige Witze über eine externe API abruft

• Konversationsgedächtnis: Behält den Kontext über mehrere Nachrichten pro Benutzer

• WhatsApp-Webhook: Einfache REST-API für die Integration in WhatsApp-Dienste

• Einfaches Deployment: Funktioniert mit Express-Server, bereit für die Cloud-Bereitstellung

Related MCP server: WAHA WhatsApp MCP Server

📋 Voraussetzungen

• Node.js 18+

• npm oder yarn

• Anthropic-API-Schlüssel (erhältlich unter console.anthropic.com)

• Zugriff auf die WhatsApp Cloud API (für die Produktionsintegration)

🚀 Schnellstart

1. Projekt klonen und installieren

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

2. Umgebungsvariablen festlegen

cp .env.example .env

Bearbeite .env und füge deinen Anthropic-API-Schlüssel hinzu:

ANTHROPIC_API_KEY=your_anthropic_api_key_here
PORT=3000

3. Server starten

npm start

Du solltest Folgendes sehen:

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

📡 API-Nutzung

Health Check

curl http://localhost:3000/health

Nachricht an Claude senden

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

Antwort:

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

Konversationsverlauf löschen

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

🛠️ Verfügbare Tools

Witzgenerator

Claude kann dieses Tool automatisch verwenden, wenn es passt:

• Auslöser: Wenn der Benutzer nach Witzen fragt

• Typen: random, programming, general

• API: Official Joke API

Beispielinteraktion:

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

📁 Projektstruktur

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

🔌 Integration in WhatsApp

Option 1: WhatsApp Cloud API

Für die Produktion die WhatsApp Cloud API integrieren:

1. Richte einen Webhook auf der Meta Business Platform ein

2. Lege die Webhook-URL fest auf: https://your-domain.com/webhook/whatsapp

3. Wenn WhatsApp Nachrichten sendet, bitte leite sie an diesen Endpunkt weiter.

Option 2: Lokale Tests

Verwende Tools wie curl, Postman oder ein Testskript, um Nachrichten zu senden:

// 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);

🧠 So funktioniert es

1. Nachricht empfangen → WhatsApp-Webhook empfängt eine Nachricht

2. Claude-Verarbeitung → Die Nachricht wird mit den verfügbaren Tools an Claude gesendet

3. Tool-Auswahl → Claude entscheidet, ob Tools benötigt werden

4. Tool-Ausführung → Der MCP-Server führt die Tools aus (z. B. Witze abrufen)

5. Antwortgenerierung → Claude erstellt eine Antwort anhand der Tool-Ergebnisse

6. Nachricht senden → Die Antwort wird über WhatsApp zurückgesendet

🚀 Weitere Tools hinzufügen

Um ein neues Tool hinzuzufügen (z. B. Wetter, Übersetzungen):

1. Tool-Datei erstellen

// 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. Im MCP-Server registrieren

// 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);
      // ...
    }
  }
}

📚 API-Referenz

POST /webhook/whatsapp

Request-Body:

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

Antwort:

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

POST /webhook/clear-history

Request-Body:

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

Antwort:

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

🔐 Sicherheitshinweise

• API-Schlüssel: Committe die .env-Datei niemals in die Versionskontrolle

• Rate-Limiting: Ziehe ein Rate-Limiting für die Produktion in Betracht

• Eingabevalidierung: Validiere immer die Webhook-Payloads

• HTTPS: Verwende in der Produktion HTTPS

• Authentifizierung: Füge eine Webhook-Signaturprüfung für die WhatsApp-Integration hinzu

📝 Umgebungsvariablen

🤝 Mitwirken

Forke das Projekt, modifiziere es und trage gerne etwas bei!

📄 Lizenz

MIT-Lizenz – Details findest du in der LICENSE-Datei.

🆘 Fehlerbehebung

„API key not found“

• Stelle sicher, dass .env existiert und ANTHROPIC_API_KEY gesetzt ist

• Prüfe, ob der Schlüssel unter console.anthropic.com gültig ist

„Tool execution failed“

• Prüfe, ob die externen APIs erreichbar sind

• Überprüfe die Netzwerkverbindung

• Sieh dir die Fehlerprotokolle in der Konsolenausgabe an

„No response from Claude“

• Prüfe, ob ANTHROPIC_API_KEY korrekt ist

• Stelle sicher, dass das Claude-Modell verfügbar ist

• Prüfe die API-Rate-Limits

📞 Support

Bei Problemen oder Fragen:

1. Sprich den Abschnitt zur Fehlerbehebung an

2. Lies dir die Claude-API-Dokumentation durch

3. Eröffne ein Issue auf GitHub

🎯 Zukünftige Erweiterungen

• Unterstützung für Bilder/Medien in WhatsApp-Nachrichten

• Weitere Tools (Wetter, Nachrichten, Übersetzungen)

• Datenbank für dauerhaften Gesprächsverlauf

• Rate-Limiting und Authentifizierung

• Admin-Dashboard zur Überwachung

• Mehrsprachige Unterstützung

• Maßgeschneiderte Claude-Systemprompts pro Benutzer

Mit ❤️ erstellt von yulianheroes-lgtm