wazap-mcp

██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
╚███╔███╔╝██║  ██║███████╗██║  ██║██║
 ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝

WhatsApp für deinen KI-Agenten. Ein MCP-Server, der dein WhatsApp-Konto – Chats, Nachrichten, Medien, Kontakte, Gruppen – hinter 22 Tools stellt, die jeder MCP-Client aufrufen kann. Anmeldung per Pairing-Code, kein Browser, kein Telefonnummern-Wiederverkäufer, ~20 MB RAM.

Basiert auf Baileys, das das WhatsApp-Multi-Device-Protokoll über eine WebSocket-Verbindung spricht.

Erste Schritte

Das npm-Paket ist wazap-mcp; der Befehl, den es installiert, ist wazap.

npx wazap-mcp setup

Das ist die gesamte Installation. Es verknüpft dein Konto, findet die auf diesem Rechner installierten MCP-Clients, schreibt deren Konfiguration und sagt dir, was du neu starten musst.

Oder lass deinen Agenten das erledigen. Füge dies ein:

Richte WhatsApp für mich ein: Führe npx wazap-mcp setup --agent aus und folge dem, was es ausgibt.

Dann frag deinen Agenten: „Was habe ich heute auf WhatsApp verpasst?"

Im Folgenden sind die Schritte, die setup für dich ausführt. Jeder ist weiterhin ein eigener Befehl, wenn du ihn von Hand ausführen möchtest.

npx wazap-mcp login zeigt einen QR-Code; scanne ihn unter Einstellungen → Verknüpfte Geräte → Gerät verknüpfen. Keine Kamera zur Hand oder Verknüpfung über SSH? npx wazap-mcp login --phone +15550100 gibt einen 8-stelligen Code aus, den du unter Stattdessen mit Telefonnummer verknüpfen eingibst. Am Ende fragt es, ob der Agent Nachrichten senden darf; die Antwort ist nein, es sei denn, du sagst ja, und npx wazap-mcp config writes on ändert das später.

npx wazap-mcp connect claude-code schreibt den MCP-Eintrag für einen Client. Die Tabelle unter Client verbinden enthält den Rest.

npx wazap-mcp allein ist sicher auszuführen: Es zeigt, wo du stehst und was als Nächstes zu tun ist, und startet keinen Server. Wenn etwas nicht stimmt, ist npx wazap-mcp status das Erste, was du ausführen solltest – es prüft Node, das Datenverzeichnis, die Sperre, die Anmeldedaten und ob eine neuere Version verfügbar ist, und zeigt neben jedem Problem die Lösung an.

Client verbinden

wazap connect <client> schreibt den Eintrag für dich, behält alles andere in der Datei und sichert sie einmal vor der ersten Änderung. --dry-run zeigt, was es schreiben würde.

Jeder MCP-Client funktioniert auf die gleiche Weise: Der Befehl ist npx -y wazap-mcp, der Transport ist stdio. Sag dem Agenten, er soll zuerst learn aufrufen – es gibt die ID-Formate, die Arbeitsabläufe und jeden Fehlercode mit Hinweisen zur Behebung zurück.

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "wazap-mcp"]
    }
  }
}

Claude Desktop, Cursor und Gemini CLI übernehmen genau das. VS Code verschachtelt es unter servers und möchte ein "type": "stdio" neben command. Codex CLI ist TOML:

[mcp_servers.whatsapp]
command = "npx"
args = ["-y", "wazap-mcp"]

Der Ordner skills/ folgt dem Agent Skills-Format, sodass Codex, Cursor und andere skill-bewusste Agenten dieselben fünf Skills laden können.

Related MCP server: wa-bridge

Tools

Jede Nachricht wird mit einem nicht-leeren text zurückgegeben: Medien- und Systemnachrichten enthalten einen Platzhalter wie [image] caption, [voice message], [deleted] oder [poll] Pizza or pasta?. Zeitstempel sind ISO 8601 mit dem UTC-Offset der Maschine, zusammen mit einem menschlichen age wie 2h ago.

Skills

wazap enthält fünf Agent Skills, die einem Agenten die Arbeitsabläufe hinter den Tools beibringen, nicht nur die Tools:

Installiere alles (Server und Skills) als Claude-Code-Plugin:

/plugin marketplace add razvangirgiz/wazap
/plugin install wazap@wazap

Oder kopiere skills/<name>/ in ein beliebiges Skills-Verzeichnis, das dein Agent liest.

Fehler

Jeder Fehler ist ein strukturiertes { error, message, fix } anstelle eines Stack-Trace, sodass ein Agent entscheiden kann, ob er es erneut versuchen, den Benutzer fragen oder aufhören soll.

Datenverzeichnis

Alles befindet sich in ~/.wazap (überschreibbar mit --data-dir oder WAZAP_DATA_DIR), erstellt mit 0700 und Anmeldedaten mit 0600 geschrieben:

~/.wazap/
  auth/         WhatsApp credentials — treat this like a password
  media/        downloads from download_media
  history/      per-chat message history, so a restart is not amnesia
  store.json    chat-list snapshot
  server.lock   pid of the running server
  daemon.json   loopback endpoint a second wazap bridges to
  .env          optional settings, see .env.example

Anmeldedaten werden in eine temporäre Datei geschrieben und dann an Ort und Stelle umbenannt, sodass ein Abbrechen des Prozesses während des Schreibens nicht dazu führen kann, dass du dein Telefon erneut verknüpfen musst.

Mehrere Clients gleichzeitig

{"type": "text"}

Claude Desktop, Claude Code und Cursor starten jeweils ihr eigenes wazap. WhatsApp erlaubt einen Socket pro verknüpftem Gerät, daher teilen sie sich eine Sitzung, statt darum zu kämpfen. Das erste wazap in einem Datenverzeichnis besitzt die Sitzung und öffnet einen MCP-Endpunkt auf 127.0.0.1; jedes weitere stellt über diesen Endpunkt eine Brücke zu ihm her. Es gibt nichts zu konfigurieren, und kein Client kann den Unterschied erkennen. Der Besitzer veröffentlicht <data-dir>/daemon.json (0600) mit seiner PID, seinem Port und dem Token, mit dem sich eine Brücke authentifiziert.

Eine Brücke bedient das, was der Besitzer bereitstellt, sodass ein mit --read-only gestarteter Besitzer jeden Client schreibgeschützt macht, unabhängig davon, mit welchen Flags dieser Client gestartet wurde.

Wenn der Besitzer beendet wird, beenden sich auch die Brücken mit ihm, und das nächste wazap, das ein Client startet, wird der neue Besitzer.

WAZAP_NO_SHARE=1 verzichtet darauf: Ein zweites wazap im selben Verzeichnis beendet sich mit Code 2 und nennt die PID des bereits laufenden. Ein explizites --http ist ein eigener Server statt einer Brücke und wird auf dieselbe Weise abgelehnt.

Schreibgeschützter Modus

Schreibvorgänge sind Opt-in. login fragt einmal nach und speichert die Antwort in <data-dir>/.env; wazap config writes on|off ändert sie, und wazap config allein gibt jede wirksame Einstellung samt ihrer Herkunft aus.

WAZAP_READ_ONLY=1 oder wazap serve --read-only registriert die Schreib-Tools gar nicht erst. Der Agent sieht sie nie und kann daher niemanden von Ihrer Nummer aus anschreiben, nicht einmal versehentlich – nützlich, wenn das verknüpfte Konto Ihr persönliches ist.

Schreibvorgänge sind außerdem auf WAZAP_RATE_LIMIT pro Minute begrenzt (Standard 20, 0 deaktiviert). Schneller zu senden, als ein Mensch es täte, ist ein Weg, wie Konten gesperrt werden.

HTTP-Modus

WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32) \
npx wazap-mcp serve --http --host 0.0.0.0 --port 8766

Streamable HTTP unter /mcp, mit einem Health-Check unter /healthz. Zwei Bearer-Tokens: Das Lese-Token erhält die Lese-Tools, das Schreib-Token schaltet zusätzlich die Schreib-Tools frei, sodass ein durchgesickertes Lese-Token niemals jemanden anschreiben kann. wazap weigert sich, eine Nicht-Loopback-Adresse ohne Lese-Token zu binden.

Selbst gehostet

Betreiben Sie wazap auf einem eigenen Server, wenn der Agent nicht auf Ihrem Laptop läuft: einem anderen Rechner, einem VPS, der Infrastruktur eines Kunden. Die Sitzung bleibt auf diesem Server; nichts läuft über einen Dritten.

Mit systemd

npm install -g wazap-mcp
sudo useradd --system --home /var/lib/wazap --create-home wazap
sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
WAZAP_READ_TOKEN=$(openssl rand -hex 32)
WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
END
sudo curl -fsSL https://raw.githubusercontent.com/razvangirgiz/wazap/main/deploy/wazap.service -o /etc/systemd/system/wazap.service
sudo systemctl enable --now wazap
curl -s http://127.0.0.1:8766/healthz

Die Unit bindet nur Loopback. Setzen Sie TLS davor mit der zweizeiligen deploy/Caddyfile (caddy run --config deploy/Caddyfile nach dem Bearbeiten des Hostnamens) oder einem beliebigen Reverse-Proxy, und richten Sie den Client dann auf https://your-host/mcp mit Authorization: Bearer <Lese- oder Schreib-Token> aus.

Mit Docker

git clone https://github.com/razvangirgiz/wazap && cd wazap
printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
docker compose up -d
curl -s http://127.0.0.1:8766/healthz

Der Container veröffentlicht 8766 nur auf Loopback; fügen Sie denselben TLS-Proxy davor hinzu. Ein Upgrade ist git pull && docker compose up -d --build; das Volume behält die Sitzung.

Welche Clients darauf zugreifen können

Claude Code, Claude Desktop, Cursor, Codex, VS Code und jeder Client mit einem Feld „MCP-URL + Header" verbinden sich mit dem Bearer-Token. claude.ai-Connectors erfordern OAuth statt eines statischen Tokens und können daher noch kein selbst gehostetes wazap verwenden. Behalten Sie das Lese-Token in Clients, die nur lesen müssen; geben Sie das Schreib-Token bewusst heraus.

Einstellungen

Flags schlagen Umgebungsvariablen, die wiederum <data-dir>/.env schlagen.

Bekannte Einschränkungen

• Inoffiziell. Baileys hat das WhatsApp-Multi-Geräte-Protokoll per Reverse Engineering erschlossen. Dies ist nicht die WhatsApp Business API, und Meta unterstützt es nicht.

• Sperrrisiko ist real. Automatisiertes Senden, Massen-Nachrichten oder alles, was ein Mensch nicht plausibel tippen würde, kann zur Sperrung der Nummer führen, und das ist von hier aus nicht rückgängig zu machen. Die Ratenbegrenzung hilft; sie ist keine Garantie.

• Medienschlüssel laufen ab. WhatsApp entfernt alte Anhänge von seinen Servern, daher gibt download_media bei einer alten Nachricht MEDIA_UNAVAILABLE zurück.

• Der Verlauf ist das, was das Telefon synchronisiert. wazap sieht den Verlauf, den WhatsApp dem verknüpften Gerät übergibt, nicht Ihr vollständiges Telefonarchiv. read_messages mit before fragt nach mehr, innerhalb dessen, was WhatsApp noch aufbewahrt.

• @lid-IDs. Neuere Konten werden über eine Datenschutz-ID statt einer Telefonnummer adressiert. wazap übersetzt sie zurück in Telefonnummern, wenn es die Zuordnung gelernt hat, und reicht die @lid durch, wenn nicht.

• Ihr Telefon muss erreichbar bleiben. Ein verknüpftes Gerät empfängt nicht mehr, sobald das Telefon lange genug offline war; get_status sagt das in hint.

Entwicklung

npm install
npm run typecheck
npm test                       # builds, then runs node --test
node test/smoke-stdio.mjs      # drives the built binary over MCP stdio
npm run dev -- status          # run from source with tsx

npm test benötigt keine WhatsApp-Sitzung. Der Stdio-Smoke-Test startet die gebaute Binärdatei mit einem Wegwerf-Datenverzeichnis und prüft, ob eine nicht verknüpfte Installation weiterhin initialize, tools/list und get_status beantwortet.

MIT-lizenziert.