WhatsApp MCP

whatsapp-mcp

whatsmeow を直接ベースに構築された、Claude 向けの WhatsApp MCP サーバーです。保存データは暗号化され、プロンプトインジェクションを除去し、送信のたびに下書きと確認を行い、完全な監査証跡を記録します。セキュリティチェックを毎日 CI で実施し、積極的にメンテナンスしています。

この実装の特徴

最もスター数の多い WhatsApp MCP（lharries/whatsapp-mcp、5.6K スター）は、このパターンの設計上の参考になりますが、2025 年 7 月以降リリースされておらず、致命的な三要素の問題をすべてユーザーに委ねています。この実装では、次の点を解決しています。

	標準実装	この実装
最終リリース	2025 年 7 月	継続的に更新
データベースの暗号化	暗号化なしの SQLite	プラットフォームのシークレットストア（macOS Keychain / Windows Credential Manager / libsecret）に鍵を保存する SQLCipher
プロンプトインジェクション除去	なし	受信メッセージごとに実施
送信の安全性	即時送信	下書きから送信までの間に、必須の confirm_send を実行
監査ログ	なし	すべてのツール呼び出しを記録、30 日間保持
音声メッセージ	文字起こしなし	ローカルの whisper.cpp、スペイン語に調整済みの設定がデフォルト
LID エイリアス解決	上流で未解決の課題が複数	実装済み。既存のスレッド向けバックフィル移行も用意
CI セキュリティ	なし	govulncheck + pip-audit + Dependabot を毎日実行

フォークではありません。Go ブリッジは whatsmeow を直接ベースに構築されており、Python MCP レイヤーと SQLite スキーマは独自に作成されています。他の実装（lharries、LukasHaas、verygoodplugins）は参考として読んだだけです。

できること

Claude は次の操作を行えます。

• WhatsApp のチャット、メッセージ、連絡先を閲覧する
• アクセント記号を無視し、誤字にも対応する検索でメッセージを検索する
• whisper.cpp を使って音声メッセージをローカルで文字起こしする（デフォルトでスペイン語に調整済み）
• 数値のプレースホルダーではなく、LID（Linked IDentifier）の名前を解決する
• テキストメッセージ、リアクション、引用返信を送信する（下書きから送信までの間に、必須の confirm_send ステップを実行）
• チャットを読む際に、Obsidian の保管庫から該当する CRM コンテキストを取得する
• プロンプトインジェクションを除去したメッセージ本文のみを参照し、悪意のある入力そのものは参照しない

すべての処理はお使いのマシン上でローカルに実行されます。クラウド同期もテレメトリーもありません。OpenAI Whisper バックエンドはオプションで利用できますが、明示的に有効にしない限り無効です。

アーキテクチャ

2つのコンポーネントで構成され、どちらもローカルで動作します。

• whatsapp-bridge/（Go）。127.0.0.1 のみでバインドします。WhatsApp Web のマルチデバイスプロトコル用に whatsmeow をラップしています。SQLCipher による暗号化を使用して SQLite にデータを永続化します。QR コード認証とペアリングコード認証（Windows でも安全に描画でき、リアルタイムで更新されるターミナル QR コードに加えて、GUI やスーパーバイザーがターミナルを使わずにペアリングを実行できるヘッドレス認証 API — GET /api/auth/qr、POST /api/auth/pair-phone、POST /api/auth/reconnect）を処理します。メディアのアップロードとダウンロード、StreamReplaced 競合からのセッション復旧、通話履歴の取得にも対応しています。Python MCP レイヤーが利用する REST API を公開します。
• whatsapp-mcp-server/（Python、FastMCP）。Go ブリッジの REST API を利用します。Claude に 11 個の MCP ツールを公開します。読み取り機能一式（チャット、メッセージ、連絡先）、アクセント記号を区別しない検索、プレゼンス（入力中、オンライン、既読にする）、およびテキスト送信とリアクション、引用返信に対応し、送信時には必ず confirm_send が必要です。uv と stdio トランスポートを使用して実行します。

インストール

Claude Code を開き、次を貼り付けます。

/plugin marketplace add adelaidasofia/whatsapp-mcp
/plugin install whatsapp-mcp@whatsapp-mcp

これにより Python MCP サーバー側がインストールされます。Go ブリッジでは、引き続きスマートフォンを使った QR コードのペアリングが一度必要です。手順については、以下の従来のインストール手順をご覧ください。

手動インストール（Go ブリッジ全体 + QR コードペアリング）

OS ごとの手順については、SETUP.md をご覧ください。概要は次のとおりです。

1. Releases からビルド済みブリッジバイナリを入手する（Windows/macOS/Linux — コンパイラーは不要です）。またはソースからビルドする（Go 1.26 以降と C ツールチェーンが必要です）。
2. MCP サーバーレイヤー用に Python 3.11 以降と uv を用意します。
3. このリポジトリをクローンし、scripts/check_prerequisites.sh で確認します（Windows の場合は scripts\check_prerequisites.ps1）。
4. ブリッジを起動します：./bin/whatsapp-bridge（Windows の場合：.\bin\whatsapp-bridge.exe）。
5. QR コードをスキャンします（画面上で更新されるため、必ず表示中の QR コードをスキャンしてください）。または、--pair-phone +15551234567 を使ってコードを入力し、ペアリングします。
6. Claude Code の .mcp.json に MCP を登録します。
7. Claude Code を再起動します。

音声メモの文字起こしを有効にする場合のみ FFmpeg と whisper.cpp が必要です（デフォルトでは無効です）。

設定

すべて環境変数で設定できます。一覧については .env.example をご覧ください。

主な変数：

変数	デフォルト	用途
WHATSAPP_BRIDGE_PORT	8080	Go ブリッジの REST API ポート
WHATSAPP_DB_PATH	$HOME/.claude/whatsapp-mcp/store/messages.db	暗号化された SQLite データベース
WHATSAPP_MEDIA_PATH	$HOME/.claude/whatsapp-mcp/media/	メディアファイルの保存先
WHATSAPP_VAULT_CRM_PATH	空	自動注入に使用する、Vault の CRM フォルダーの絶対パス（例：Obsidian の 👤 CRM/）。未設定の場合、CRM の注入は無効になります。
WHATSAPP_WHISPER_BACKEND	off	off（設定なしで起動）、local-cpp（プライベート。whisper モデルが必要）、または openai-api（オプトイン）
WHATSAPP_WHISPER_API_KEY	空	バックエンドが openai-api の場合のみ必要です
WHATSAPP_WHISPER_MODEL	large-v3	whisper.cpp のモデル名
WHATSAPP_SCRUB_PROMPT_INJECTION	true	Claude に表示する前に、受信メッセージから既知のプロンプトインジェクションパターンを除去します
WHATSAPP_AUDIT_LOG	true	すべてのツール呼び出しを audit.log に記録します
WHATSAPP_ENCRYPT_DB	true	SQLCipher による DB 暗号化を有効にします。キーはプラットフォームのシークレットストア（macOS Keychain / Windows Credential Manager / libsecret）に保存されます
WHATSAPP_DB_KEY	空	SQLCipher 用の 64 桁の 16 進数キーを明示的に指定します（プラットフォームのストアを使いません）。ヘッドレス環境、CI、カスタムシークレットマネージャー向けの緊急用設定であり、シークレットストアを読み取れない場合の復旧手段でもあります。詳細は以下をご覧ください

DB キーと WHATSAPP_DB_KEY

WHATSAPP_ENCRYPT_DB=true（デフォルト）の場合、ブリッジはプラットフォームのシークレットストアに保存された 256 ビットの SQLCipher キーでメッセージストアを暗号化します。誤ったキーを使うと、保存されたすべてのメッセージにアクセスできなくなるため、キーのライフサイクルは意図的に慎重に管理しています。

• シークレットストアから「項目なし」という確実な応答（macOS の errSecItemNotFound、Windows の ERROR_NOT_FOUND、libsecret の正常な未検出）を受け取り、かつ空でないストアデータベースがまだ存在しない場合に限り、新しいキーを生成します。
• それ以外の読み取りエラー（キーチェーンのロック、D-Bus セッションの不在、アクセス権の取り消しなど）が発生した場合、ブリッジはキーを生成せず、エラーを返して終了します。キーがまだ存在している可能性があり、上書きすると暗号化されたストアを永久に復号できなくなるためです。エラーには対処方法（例：security unlock-keychain）が示されます。
• シークレットストアにキーがなく、データが格納されたストアデータベースが存在する場合も、ブリッジはキーの生成を拒否し、元のキーを指定するよう求めます。

WHATSAPP_DB_KEY（16 進数 64 文字＝32 バイト。例：openssl rand -hex 32）を設定すると、これらすべての状況に対応できます。設定時はキーが直接使用され、プラットフォームのシークレットストアには一切アクセスしません。ヘッドレス環境や CI 環境のマシン、カスタムシークレットマネージャーの利用、新しいマシンへのストアの復元、プラットフォームのストアが利用できない状態での起動に使用してください。

セキュリティ

受信するすべての WhatsApp メッセージがこの MCP を経由するため、これは Claude スタックで最も高い信頼性が求められるコンポーネントです。脅威モデル、ツールのリスク階層の分類、強化に関する決定事項の全一覧については、SECURITY.md を参照してください。

概要：

• ブリッジは 127.0.0.1 のみにバインドし、0.0.0.0 にはバインドしません
• SQLite は SQLCipher で保存時に暗号化されます。キーはプラットフォームのシークレットストア（macOS Keychain／Windows Credential Manager／libsecret）に保存され、WHATSAPP_DB_KEY による代替手段も用意されています
• すべてのツール呼び出しを audit.log に記録し、30 日間保持します
• メッセージ送信ツールでは、下書きの作成と送信の間に明示的な confirm_send 手順が必要です
• 受信メッセージのテキストは、Claude に渡す前にプロンプトインジェクション除去処理を通ります
• whatsmeow は特定のコミットに固定されており、アップグレードには差分のレビューが必要です
• デフォルトではテレメトリーも外部 API 呼び出しもありません

ステータス

v0.1.0。積極的にメンテナンスされています。

リリース済み：ライブ更新される QR コード（ローテーション時のインプレース再描画、Windows に対応した描画、有効期限切れ時の自動再生成）＋ペアリングコード認証（8 文字のコードを入力。Android と iOS に対応）＋スーパーバイザー向けのヘッドレス認証 API、読み取り機能一式（チャット、メッセージ、連絡先）、アクセント記号を区別しない NFD 正規化検索、過去のスレッドを補完するバックフィルマイグレーションを備えた LID エイリアス解決、履歴を一度だけ移行する Baileys ストアのインポート、ボルト形式の Markdown エクスポート、ローカル whisper.cpp による音声文字起こし、プレゼンス（入力中、オンライン、既読化）、必須の confirm_send を伴うテキスト送信、リアクション、返信引用、プロンプトインジェクション除去処理、macOS Keychain のキー管理を伴う SQLCipher 暗号化永続化、監査ログ、CI セキュリティゲート。

未リリース：メディア送信（画像、ドキュメント）、音声メッセージ送信（FFmpeg-Opus 経由）、グループ一斉配信ヘルパー。

全履歴については CHANGELOG.md を参照してください。

MCP レジストリ

公式 MCP レジストリにio.github.adelaidasofia/whatsapp-mcpとして公開されています。現在、2 つの配布チャネルがあります。

• .mcpb バンドル（正式版、推奨）— Claude Desktop／Cursor／その他のMCPB対応クライアントにワンクリックでインストールできます。GitHub リリースのアーティファクトとしてreleases/latest/download/whatsapp-mcp.mcpbに公開されています。リリースマニフェストには、改ざん検知用の SHA256 が含まれています。
• PyPI パッケージ（adelaidasofia-whatsapp-mcp）— 旧版です。stdio インストーラーのフローでは、uvx adelaidasofia-whatsapp-mcpから利用できます。プレフィックスのない名前（whatsapp-mcp、whatsapp-mcp-server）は、PyPI 上の無関係なプロジェクトで使用されているため、ユーザー名をプレフィックスとする名前空間を使用しています。

検証マーカーmcp-name: io.github.adelaidasofia/whatsapp-mcpは、公開時にレジストリがパッケージとサーバーの所有権を確認できるよう、この README の上部付近にある HTML コメント内に埋め込まれています。

公開パイプライン： Mycelium MCP 公開パイプラインを通じてビルドおよびリリースされます（2 段階：.mcpb バンドルのビルド後、gh releaseとmcp-publisher publishを実行）。このファミリーの関連 MCP 16 個も、同じパイプラインで公開されました。

関連 MCP

同じ作者、同じアーキテクチャパターン（FastMCP、該当する場合は書き込み時にドラフト＋確認、ボルトの自動エクスポート、MIT）：

• slack-mcp — 複数の Slack ワークスペース
• imessage-mcp — macOS の iMessage
• google-workspace-mcp — Gmail／Calendar／Drive／Docs／Sheets
• apollo-mcp — Apollo.io の CRM とシーケンス
• substack-mcp — Substack の執筆と分析
• luma-mcp — lu.ma のイベント
• parse-mcp — markitdown／Docling／LlamaParse のルーター
• rescuetime-mcp — RescueTime の生産性データ
• graph-query-mcp — ボルトのナレッジグラフクエリ
• graph-autotagger-mcp — グラフからのウィキリンク候補
• investor-relations-mcp — シード資金調達パイプラインのトラッカー
• vault-sync-mcp — 双方向のボルト同期

テレメトリ

このプラグインは、特定のマシンで Claude Code セッション中に初めて読み込まれた際、匿名のインストール通知を 1 回だけmyceliumai.coに送信します。

送信される情報：

• プラグイン名（例：slack-mcp）
• プラグインのバージョン（例：0.1.0）

送信されない情報：

• ユーザー識別子、名前、メールアドレス、トークン、API キーは送信されません
• ファイルパス、メッセージ内容、または作業に関する情報は送信されません
• 重複排除処理後、IP アドレスは保存されません

目的： メンテナーが実際にインストールされているプラグインを把握し、利用されているプラグインに注力できるようにします。

オプトアウト： Claude Code を起動する前に、環境変数MYCELIUM_NO_PING=1を設定してください。フックはネットワーク呼び出しを完全にスキップします。通知済みのインストールでは~/.mycelium/onboarded-<plugin>にセンチネルが残ります。状態をリセットしたい場合は削除してください。

ライセンス

MIT。LICENSEを参照してください。

WhatsApp または Meta とは無関係です

WhatsApp は Meta Platforms, Inc. の商標です。このプロジェクトは、WhatsApp の公開ウェブマルチデバイスプロトコルを使用する独立したオープンソースツールです。このツールの使用は、WhatsApp の利用規約に違反する可能性があります。ご自身の責任でご利用ください。作者は一切の保証を行わず、アカウントの停止、データの損失、その他の結果について一切の責任を負いません。

---

Mycelium AI が開発。MIT ライセンス。