Guarded WhatsApp

AI エージェント（または任意の MCP クライアント）が WhatsApp のメッセージやファイルを送信できる MCP サーバーです。ただし、すべての送信は、管理者が制御するセキュリティゲートを通過する必要があります。セキュリティゲートには、送信先の許可リスト、シークレットスキャン、ファイル検証、レート制限、確認ゲート、追記専用の監査ログが含まれます。

ほとんどの WhatsApp ブリッジは、記録を残さずに、どこへでも何でも送信します。人間が 送信 をクリックするのであれば問題ありません。しかし、自律型エージェントには適しません。guarded-whatsapp-mcp はガバナンスレイヤーとして、エージェントによる WhatsApp の利用を、安心して任せられるほど安全にします。

これは Slack の代替ではありません。 チャンネルもスレッドもワークスペース UI もありません。すでに利用している WhatsApp を安全に自動化します。

動作を確認する

仕組み

---

⚠️ まずお読みください — 非公式の通信方式と WhatsApp の利用規約

このサーバーは通信方式へのアクセスを管理します。デフォルトでは、その通信方式は、WhatsApp Web の非公開プロトコルを使用する非公式の whatsmeow ベースのブリッジ（例：whatsapp-mcp）です。

• 非公式クライアントはWhatsApp の利用規約に違反し、電話番号が利用停止になる可能性があります。リバースエンジニアリングされたクライアントでは、これを避けられません。
• サブの番号、または重要ではない番号を使用してください。 メインの番号や、業務に不可欠な番号は絶対に使用しないでください。
• 本番環境での顧客向けメッセージ送信には使用しないでください。公式の WhatsApp Business Cloud API をご利用ください。公式の Cloud-API バックエンドはロードマップに含まれています。ガードレイヤーは、どちらの通信方式にも対応できるよう設計されています。

ここで提供するガードレールは、送信先の誤り、シークレットの漏えい、スパムなどの運用上のリスクを軽減します。ただし、基盤となるブリッジに関する利用規約上のリスクは変わりません。この点をあえて強調しています。リスクを十分に理解したうえで選択できるようにするためです。

---

チームで利用する理由

ガードなし	guarded-whatsapp-mcp を利用
エージェントが生成した任意の番号にメッセージを送信できる	フェイルクローズ方式の許可リストにより、未登録の相手への送信を拒否
漏えいした API キーがメッセージに含まれたまま送信される	送信前にシークレットスキャンでブロック
暴走したループがチームに 200 回スパムを送信する	レート制限で上限を設定
ファイル名が Untitled になり、パスも未検証	ASCII セーフなファイル名と種類・サイズのチェック
エージェントが何を送信したのかわからない	すべての試行を記録する追記専用の監査ログ
誤送信	確認ゲートにより、リスクのある送信にはプレビューが必須

セキュリティ制御

制御	機能
宛先許可リスト	フェイルクローズ方式です。allow_unlisted: false の場合、設定に登録された人またはグループにのみメッセージを送信できます。生の電話番号であっても拒否されます。
シークレット／PII スキャン	テキストとキャプションをスキャンし、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"
      }
    }
  }
}

例 — 安全なエージェントのフロー

// 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（準拠ルート）の前段で、同じガードレイヤーを使用します。
• 受信メッセージのルーティング — エージェントに受信メッセージを提示します（読み取り・分類・ルーティング）。
• 同じゲートを通じた スケジュール送信／テンプレート送信。
• 宛先ごとのポリシー（連絡先またはグループごとのレート制限／確認ルール）。

テスト

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

コントリビューション

プルリクエストを歓迎します。CONTRIBUTING.md を参照してください。唯一のルールは、フェイルクローズの方針を維持することと、新しいチェックごとにテストを追加することです。

ライセンス

MIT — LICENSE を参照してください。セキュリティモデルと正直な制限事項については SECURITY.md を参照してください。