wa — safe WhatsApp automation MCP server

wa

Personal WhatsApp automation CLI + daemon, written in Go.

A hexagonal Go daemon that owns a WhatsApp Multi-Device session and a thin JSON-RPC client that talks to it — safe enough to let a language model send messages on your behalf, crash-safe enough to survive a power loss mid-migration, and paranoid enough to refuse every destructive flag you might expect.

Quickstart · Install · Manual · Architecture · Security · Contributing · Português (BR)

Capability

Pattern. Persistent WhatsApp daemon over a Unix socket — one wad process holds the Multi-Device session, ratchet store, and websocket; a thin wa JSON-RPC client invokes it.

Trade-off. ~30 MB RSS per profile and a 5–8 s cold connect, in exchange for sub-second warm-call latency on every subsequent wa send. Per-call session reattachment is avoided entirely.

Use when. A shell pipeline, cron job, or Claude Code plugin needs to dispatch WhatsApp messages with predictable latency and a non-overridable safety pipeline (default-deny allowlist + rate limiter + warmup ramp + append-only audit log) sitting below every RPC path.

brew install yolo-labz/tap/wa
wad &                                                # daemon, single instance per profile
wa pair                                              # QR-code pairing on first run
wa allow add 5511999999999@s.whatsapp.net --actions send
wa send --to 5511999999999@s.whatsapp.net --body "hello"

Demo

Every frame is real output from the binaries in this repo, recorded against a throwaway unpaired daemon in a private temp directory. doctor honestly warns that the device is unpaired (and may flag missing backups in the fresh sandbox). No real account data is used. The revoke command is help only, not a mutation.

The recording is generated, never hand-edited. The source of truth is the plain-text docs/assets/wa-demo.tape; regenerate the GIF, MP4, WebM, static PNG and captured text with one command:

nix develop -c ./scripts/record-demo.sh

Prefer playback controls or reduced motion? Use MP4, WebM, the static frame, or the text equivalent. Recording notes cover isolation, safety controls, byte budgets and checks. Playback is 1× and silent; no live sends are demonstrated.

How wa compares

Shortened. The full README is on GitHub.