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

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-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.