WhatsApp MCP Stream

Ein WhatsApp-MCP-Server, der auf Streamable HTTP-Transport basiert, Baileys für die WhatsApp-Anbindung verwendet und über eine Web-Admin-Oberfläche sowie bidirektionalen Medienfluss (Upload + Download) verfügt.

Kernpunkte:

• Transport: Streamable HTTP unter /mcp

• Engine: Baileys

• Admin-UI: QR, Status, Logout, Laufzeiteinstellungen, Chatverlauf-Viewer

• Medien: Upload-Endpunkte + /media-Hosting + MCP-Download-Tool

Schnellstart (Docker)

# build and run

docker compose build

docker compose up -d

Der Server ist erreichbar unter:

• Admin-UI: http://localhost:3003/admin

• MCP-Endpunkt: http://localhost:3003/mcp

• Mediendateien: http://localhost:3003/media/<filename>

Related MCP server: lingtai-whatsapp

DNS auf Hosts mit --iptables=false

Auf einigen NAS-/gehärteten Hosts (z. B. Synology mit dockerd --iptables=false) besitzt der eingebettete DNS-Proxy von Docker (127.0.0.11) keine iptables-DNAT-Regeln und verweigert Verbindungen innerhalb von Containern.

Lösung: Kopieren Sie resolv.conf.example nach resolv.conf und fügen Sie einen Volume-Override hinzu:

cp resolv.conf.example resolv.conf

Fügen Sie dann Folgendes zu einer lokalen docker-compose.override.yml hinzu (nicht eingecheckt):

services:
  mcp-whatsapp:
    volumes:
      - ./resolv.conf:/etc/resolv.conf:ro

docker compose up übernimmt den Override automatisch.

Laufzeiteinstellungen

Einstellungen können in der Admin-UI bearbeitet und unter SETTINGS_PATH gespeichert werden (Standard: MEDIA_DIR/settings.json).

Admin-UI

Admin-Konsole mit Laufzeiteinstellungen, QR-Kopplung, Chatverlauf-Viewer, Export und Status.

Unterstützte Einstellungen:

• media_public_base_url

• upload_max_mb

• upload_enabled

• max_files_per_upload

• require_upload_token

• upload_token

• auto_download_media

• auto_download_max_mb

Authentifizierung

Eine eingebaute Authentifizierung ist noch nicht implementiert. Verwenden Sie in der Produktion ein Gateway, das die Authentifizierung durchsetzt. Dieses Projekt funktioniert gut hinter authmcp-gateway:

https://github.com/loglux/authmcp-gateway

Medien-Upload-API

Base64-JSON:

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:<base64>}

Multipart (empfohlen für große Dateien):

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

Beide geben url und (falls konfiguriert) publicUrl zurück.

Senden lokaler Dateien über send_media

Das Verzeichnis ./files/ im Projektstamm wird per Bind-Mount in den Container unter /app/files eingebunden. Legen Sie dort eine Datei ab und referenzieren Sie sie sofort – kein Container-Neustart erforderlich:

# On host:
cp report.pdf /path/to/whatsapp-mcp-stream/files/

# In send_media:
media_path: /app/files/report.pdf

Bei einer URL-Quelle übergeben Sie media_url direkt an send_media oder stage_media – der Server lädt die Datei selbst herunter, ohne base64.

Upload-Authentifizierung (optional)

Wenn require_upload_token=true gesetzt ist, übergeben Sie ein Token über eines der folgenden:

• x-upload-token: <token>

• Authorization: Bearer <token>

MCP-Transport

Der Server stellt Streamable HTTP unter /mcp bereit.

Typischer Ablauf:

1. POST /mcp mit JSON-RPC initialize

2. Verwenden Sie den zurückgegebenen mcp-session-id-Header für nachfolgende Anfragen.

3. POST /mcp für Tool-Aufrufe

Hinweis: Clients müssen bei initialize Accept: application/json, text/event-stream senden.

Smoke-Test

Kurzer Regressions-Smoke-Test für MCP-Tools:

npm run smoke:mcp

Optional benutzerdefiniertes Ziel:

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

MCP-Tools

Authentifizierung

Kontakte

Chats

Nachrichten

Medien

Dienstprogramme

Wiederherstellungshinweise

Dieser Dienst enthält einen bewusst eingebauten Wiederherstellungs-Workaround für die Korruption des Baileys/WhatsApp-Session-State.

Warum es das gibt:

• In Produktion haben wir Fälle beobachtet, in denen der Container am Leben blieb und MCP noch antwortete, die WhatsApp-Sitzung aber funktional gestört war.

• Die häufigsten Indikatoren waren Baileys-Fehler wie failed to find key ... to decode mutation und failed to sync state from version.

• In diesem Zustand stellte ein manueller Container-Neustart den Dienst oft wieder her.

Aktuelles Verhalten:

• Bei Signalen für App-State-Korruption versucht der Dienst zuerst eine sanfte Wiederherstellung mit forceResync().

• Wiederholt sich dieselbe Fehlerklasse innerhalb eines Zeitfensters, eskaliert er zu einem internen Neustart des WhatsApp-Clients.

• Bei Trennungen wie Connection Terminated plant der Dienst einen Disconnect-Watchdog und eskaliert zu einem internen Neustart, wenn der Socket nicht rechtzeitig wieder in open übergeht.

• Der Reconnect-Lebenszyklus ist gegen verschachtelte Lock-Deadlocks abgesichert, sodass die Wiederherstellung nach einer Trennung ohne manuellen Container-Neustart abgeschlossen werden kann.

• Aktuelle Produktionsbeobachtungen zeigen wiederholte Socket-Trennungen (428 Connection Terminated, 503 Stream Errored), die automatisch wieder in open überführt werden.

• Ein dedizierter /healthz-Endpunkt meldet 503 nur, wenn der Dienst tatsächlich außerhalb des zulässigen Wiederherstellungsfensters festhängt.

• Docker-Healthchecks verwenden /healthz, sodass der Container erst dann neu gestartet wird, wenn die In-Process-Wiederherstellung Gelegenheit hatte.

Diese Wiederherstellungsmechanismen reduzieren den Bedarf an manuellen Eingriffen und verbessern die Robustheit gegenüber häufigen WhatsApp/Baileys-Sitzungsfehlern.

Lizenz

MIT

Persistenz

Chats und Nachrichten werden in einer lokalen SQLite-Datenbank im Session-Volume gespeichert.

Umgebungsvariablen:

Zusätzliche Transportdiagnose:

• /mcp-POST-Anfragen protokollieren jetzt Anfrage-Lebenszyklusereignisse in logs/mcp-whatsapp.log

• dies umfasst Anfrageeingang, Transport-Dispatch, Abschluss von transport.handleRequest sowie HTTP finish / close

• Verwenden Sie diese Protokolle, um festzustellen, ob die Latenz auftritt, bevor die Antwort whatsapp-mcp-stream verlässt, oder danach auf der Gateway-/Client-Seite

Chatverlauf-API

Durchsuchen Sie gespeicherte Chats und Nachrichten über:

GET /api/chats?limit=50&offset=0&q=<search> — paginierte Chatliste, optional nach Name gefiltert.

GET /api/chats/:jid/messages?limit=50&offset=0 — paginierte Nachrichten für einen Chat (neueste zuerst).

Beide Endpunkte werden von der Registerkarte Chats in der Admin-Oberfläche verwendet.

Export

Exportieren Sie einen Chat (JSON + optional heruntergeladene Medien) über:

GET /api/export/chat/:jid?include_media=true

Wenn include_media=true, enthält das ZIP Dateien, die bereits über download_media heruntergeladen wurden. Es ruft fehlende Medien nicht von WhatsApp ab.