Guarded WhatsApp

一个 MCP 服务，可让 AI Agent（或任何 MCP 客户端）发送 WhatsApp 消息和文件，但所有操作都必须经过由你控制的安全关卡：接收方允许列表、机密扫描、文件验证、速率限制、确认关卡以及只追加的审计日志。

大多数 WhatsApp 桥接工具可以随意向任何人发送任何内容，而且不留记录。对于手动点击发送的人来说，这没问题；但对于自主 Agent 来说则不然。guarded-whatsapp-mcp 是治理层，让由 Agent 驱动的 WhatsApp 自动化足够安全，值得信赖。

这不是 Slack 的替代品。 没有频道、没有话题串、没有工作区界面。它让你已经在使用的 WhatsApp 可以安全地自动化。

实际演示

工作原理

---

⚠️ 请先阅读——非官方传输方式与 WhatsApp 服务条款

此服务负责管控对传输方式的访问；默认情况下，该传输方式是基于 非官方 whatsmeow 的桥接工具（例如 whatsapp-mcp），它使用 WhatsApp Web 的 私有协议。

• 非官方客户端违反 WhatsApp 的服务条款，并且可能导致号码被封禁。逆向工程的客户端无法避免这一点。
• 请使用备用号码或非关键号码。 切勿使用你的主号码或对业务至关重要的号码。
• 不要用于生产环境中的客户消息——请使用官方的 WhatsApp Business Cloud API。官方 Cloud API 后端已列入路线图；安全防护层的设计可用于接入这两种传输方式。

这里的安全防护措施可降低操作层面的风险（收件人错误、机密泄露、垃圾消息）， 但不会改变底层桥接工具带来的服务条款风险。我们特意把这一点说得很明确，让你在充分了解情况后再做选择。

---

团队为何使用它

无安全防护	使用 guarded-whatsapp-mcp
Agent 可以给它生成的任何号码发消息	默认拒绝的允许列表——拒绝陌生号码
泄露的 API 密钥会直接随消息发送出去	机密扫描会在发送前将其拦截
失控的循环会向团队发送 200 条垃圾消息	速率限制会设定上限
文件会显示为 Untitled；路径未经检查	仅含 ASCII 字符的安全文件名 + 类型/大小检查
不知道 Agent 发了什么	记录每次尝试的只追加审计日志
误发消息	确认关卡——高风险发送必须先预览

安全控制

控制项	作用
收件人允许列表	默认拒绝。设置 allow_unlisted: false 后，只能向配置中的个人或群组发送消息——即使是原始号码也会被拒绝。
密钥 / 个人身份信息扫描	扫描文本和说明文字中的 API 密钥、私钥、云服务 / Slack / GitHub / OpenAI 令牌、JWT、信用卡号（Luhn 算法）、国家身份证件号码。可选择 block 或 warn。
文件验证	扩展名允许列表 + 大小上限。文件名会清理为 ASCII（不使用 Untitled，不允许路径遍历）；发送前会复制为安全名称。
速率限制	滑动窗口（每分钟 + 每小时）可阻止失控循环。
确认门控	高风险发送（未列入允许列表的收件人 / 文件 / 所有发送）需要来自 wa_preview 的 confirm_token，以证明发送经过预览，而非误操作。
审计日志	每次尝试（已发送 / 已阻止 / 失败）都会追加到 ~/.guarded-whatsapp-mcp/audit.jsonl，正文仅以预览内容 + 哈希的形式存储。

工具

工具	是否受门控？	用途
wa_list_recipients	只读	显示允许列表（号码已屏蔽）。
wa_preview	只读	试运行发送：执行所有检查，并在需要时返回判定结果 + confirm_token。不会发送任何内容。
wa_send_message	发送	通过完整门控向允许列表中的收件人发送文本。
wa_send_file	发送	发送文件（自动使用安全 ASCII 名称，检查类型 / 大小，并扫描说明文字）。
wa_audit_tail	只读	查看最近的审计记录。

快速开始

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)

注册到 Claude Code / 任意 MCP 客户端

{
  "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"
      }
    }
  }
}

示例 — 安全的 Agent 工作流

// 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" }

配置

请参阅 config/allowlist.example.yaml。关键配置项： allow_unlisted（默认拒绝开关）、require_confirm_for、rate_limit、files、 secrets.on_detect 和 recipients 允许列表。每次调用时都会热加载更改。

路线图

• 可插拔后端 — 在非官方桥接服务 或 官方 WhatsApp Business Cloud API（合规路径）前使用相同的防护层。
• 入站路由 — 将收到的消息呈现给 Agent（读取 · 分类 · 路由）。
• 通过相同的门控发送定时 / 模板消息。
• 按收件人设置策略（针对每个联系人或群组设置速率限制 / 确认规则）。

测试

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

贡献

欢迎提交 PR——请参阅 CONTRIBUTING.md。唯一规则：保持默认拒绝的安全立场，并为每项新增检查添加测试。

许可证

MIT — 请参阅 LICENSE。安全模型及如实说明的限制请见 SECURITY.md。