Guarded WhatsApp

guarded-whatsapp-mcp

Govern & automate WhatsApp safely for AI agents.

An MCP server that lets an AI agent (or any MCP client) send WhatsApp messages and files — but only through a security gate you control: a recipient allowlist, secret scanning, file validation, rate limiting, a confirmation gate, and an append-only audit log.

Most WhatsApp bridges send anything, anywhere, with no record. That is fine for a human clicking *send*. It is not fine for an autonomous agent. guarded-whatsapp-mcp is the governance layer that makes agent-driven WhatsApp safe enough to trust.

This is not a Slack replacement. No channels, no threads, no workspace UI. It makes

the WhatsApp you *already use* safe to automate.

See it in action

Good sends go through · a leaked key and an un-allowlisted number are blocked · files need a preview · everything is logged.

How it works

---

⚠️ Read this first — unofficial transport & WhatsApp Terms

This server governs access to a transport; by default that transport is the unofficial [whatsmeow](https://github.com/tulir/whatsmeow)-based bridge (e.g. whatsapp-mcp), which speaks WhatsApp Web's private protocol.

• An unofficial client violates WhatsApp's Terms of Service and can get a number banned. A reverse-engineered client cannot avoid this.
• Use a secondary / non-critical number. Never your primary or business-critical one.
• Not for production customer messaging — use the official WhatsApp Business Cloud API. An official Cloud-API backend is on the roadmap; the guard layer is built to front either transport.

The guardrails here reduce operational risk (wrong recipient, leaked secret, spam). They do not change the Terms-of-Service risk of the underlying bridge. We are loud about this on purpose so you can choose with eyes open.

---

Why teams use it

Security controls

Tools

Quickstart

git clone https://github.com/peter-tnc-453/guarded-whatsapp-mcp

cd guarded-whatsapp-mcp

uv venv --python 3.11 && source .venv/bin/activate # Python 3.10+ uv pip install -e .

cp config/allowlist.example.yaml config/allowlist.yaml # edit your allowlist (git-ignored)

a WhatsApp bridge exposing POST /api/send must be running (the authenticated session).

whatsmeow bridge: https://github.com/lharries/whatsapp-mcp (first run = QR scan)

python -m wa_guard # run the MCP server (stdio)

Register with Claude Code / any MCP client

{

"mcpServers": { "guarded-whatsapp-mcp": { "command": "/ABSOLUTE/PATH/guarded-whatsapp-mcp/.venv/bin/python", "args": ["-m", "wa_guard"], "env": { "PYTHONPATH": "/ABSOLUTE/PATH/guarded-whatsapp-mcp/src", "WA_GUARD_CONFIG": "/ABSOLUTE/PATH/guarded-whatsapp-mcp/config/allowlist.yaml" } } } }

Example — a safe agent flow

// 1) The agent previews first (read-only, sends nothing)

wa_preview(recipient="Alex", file_path="report.pdf") // → { ok:false, needs_confirm:true, confirm_token:"a1b2c3d4e5", // display_filename:"report.pdf", recipient:{ name:"Alex", allowlisted:true } }

// 2) It sends, passing the token back to prove the preview happened wa_send_file(recipient="Alex", file_path="report.pdf", confirm_token="a1b2c3d4e5") // → { sent:true, ... } (and one line is appended to the audit log)

// A blocked attempt is explicit and recorded: wa_send_message(recipient="+66999999999", message="hi") // → { sent:false, blocked_reason:"recipient is not allowlisted and allow_unlisted=false" }

Configuration

See config/allowlist.example.yaml. Key knobs: allow_unlisted (the fail-closed switch), require_confirm_for, rate_limit, files, secrets.on_detect, and the recipients allowlist. Edits hot-reload on each call.

Roadmap

• Pluggable backend — same guard layer in front of the unofficial bridge *or* the official WhatsApp Business Cloud API (compliant path).
• Inbound routing — surface incoming messages to agents (read · classify · route).
• Scheduled / templated sends through the same gate.
• Per-recipient policy (rate limits / confirm rules per contact or group).

Tests

uv pip install pytest && PYTHONPATH=src python -m pytest -q   # 19 passing

Contributing

PRs welcome — see CONTRIBUTING.md. The one rule: keep the fail-closed posture, and add a test for every new check.

License

MIT — see LICENSE. Security model & honest limitations in SECURITY.md.