WhatsApp Connect

whatsapp-connect-mcp

静的な Go バイナリ 1 つで提供される WhatsApp MCP サーバーです。ダウンロードして、setup コマンドを実行し、QR コードをスキャンするだけで、あらゆる MCP クライアント（Claude Desktop、Claude Code、Cursor、Windsurf、Cline など）から WhatsApp のメッセージの読み取り、検索、送信ができるようになります。送信するメッセージはすべて、サーバー側で適用されるゲートによって保護されます。このワンステップの手順では、デフォルトの stdio トランスポートを使用します。共有 http トランスポートでは、さらにサーバーを起動して実行し続ける必要があります（インストールを参照）。

これは非公式プロトコルを使用します。大切な電話番号をペアリングする前に、こちらをお読みください。

whatsapp-connect-mcp は、whatsmeow を介して WhatsApp Web と同じ方法で WhatsApp に接続します。公式の WhatsApp Business API は使用しません。Meta は、このプロトコルでサードパーティークライアントを使用していると検知した電話番号を実際に停止しており、停止措置は永久になると広く報告されています。以下で説明する送信ゲートとレート制限機能は、このリスクの行動面（誤って大量送信してしまう、モデルが暴走するなど）を軽減します。しかし、もう一方のリスクには対処できません。このクライアント自体がサードパーティークライアントだと識別されるリスクです。停止リスクでは、公開されている情報が実際に示している内容を日付付きで説明しています。銀行や家族への唯一の連絡手段ではなく、失ってもよい電話番号をペアリングしてください。

ステータス：プレリリース。

インストール（2 分）

次のいずれかを選択してください。

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.ps1 | iex

# Anywhere with Node installed, no separate download step
npx whatsapp-connect-mcp setup
# or, sturdier for setup: a global install
npm install -g whatsapp-connect-mcp

npx whatsapp-connect-mcp serve は単独でも問題なく動作しますが、setup には上記のインストールスクリプトのいずれか、またはグローバルインストールをおすすめします。setup は、実行中のバイナリへの絶対パスを各 MCP クライアントの設定に書き込みます。npx を使うと、そのパスは npm のパッケージキャッシュ内を指すため、キャッシュを消去すると、setup が書き込んだすべてのクライアント設定が、すでに存在しないバイナリを指すことになります。グローバルインストールなら、パッケージ自体をアップグレードまたは削除するまで、バイナリは安定したパスに置かれます。

どの方法でも、お使いの OS／アーキテクチャ用のリリースバイナリをダウンロードして setup を実行します。WhatsApp でスキャンする QR コードが表示され（リンク済みデバイス → デバイスをリンク）、インストール済みの MCP クライアントが検出されます。選択したクライアントに whatsapp サーバーエントリを書き込むことができます。ツールチェーンも、JSON を手動で編集する必要もありません。

setup では、クライアントの接続方法も尋ねられます。stdio（デフォルト）では、各クライアントがそれぞれ独自のサーバープロセスを起動します。最も簡単な方法ですが、1 つの serve がデータディレクトリの排他ロックを保持するため、一度に接続できるのは 1 つのクライアントまたはセッションだけです。http では、選択したすべてのクライアントが 1 つの共有ローカルサーバー（http://127.0.0.1:<port>。ポートは任意で、デフォルトは 2178、ベアラートークンで認証）に接続するため、複数のクライアントとセッションが同時に接続できます。

http を選択しましたか？手順 2：サーバーを起動します。 サーバーは自動では起動しません。起動するまで、すべてのクライアントに http://127.0.0.1:2178 での ConnectionRefused のようなエラーが表示されます。次のコマンドを実行し、起動したままにしてください。

whatsapp-connect-mcp serve --http 127.0.0.1:2178

serve: listening on http://127.0.0.1:2178 … と表示されたあと、フォアグラウンドで動作します。そのため、ターミナルを閉じると終了します。ログアウトや再起動後も動作させるには、バックグラウンドサービスとしてインストールしてください（macOS では launchd、Linux では systemd ユーザーユニット、Windows ではタスクスケジューラのログオンタスク）。

whatsapp-connect-mcp service install

service uninstall で削除し、service restart でアップデート後に再起動します。ヘッドレス Linux マシンでは、サービスがログインセッション終了後も動作するように loginctl enable-linger を追加してください。Windows では、ユーザーのログオン時（起動時ではありません）に最小化されたコンソールウィンドウとしてサービスが実行されます。ウィンドウを閉じるとサーバーが停止します。クラッシュ時の自動再起動はありません（未ペアリング状態の serve は終了せずアイドル状態で待機するため、よくある障害ではそもそも終了しません）。タスクの作成には、管理者権限のターミナルが必要な場合があります。

続いて setup は、クライアントが読み取れる対象を尋ねます。すべてのチャット（デフォルト）、自分とのセルフチャットのみ、またはまだ何も許可しないのいずれかです。「まだ何も許可しない」を選ぶと、あとでダッシュボードまたは scope --allow からチャットを指定できます。エージェントが読み取れるチャットを参照してください。

ペアリングをやり直すときや、あとからインストールしたクライアントを追加するときなど、setup はいつでも再実行できます。

デフォルトの数か月分ではなく、プロトコルが許可する範囲でできるだけ多くの履歴をスマートフォンに要求するには、--full-history を指定します。このオプションは実際にペアリングするときのみ有効です。そのため、すでにペアリング済みのインストールでは、先に remove を実行する必要があります。setup は、このオプションを黙って無視するのではなく、その旨を伝えます。実際にどの履歴が送信されるかは、引き続きスマートフォンが決定します。

何に使うものか

14 個の読み取りツールがこの製品の中心で、10 個のゲート付き書き込みツールは便利な機能です。 実際には、次のような使い方ができます。

• 自分の履歴を検索する。 WhatsApp の検索には日付フィルターがなく、 検索結果が前後の文脈なしで表示されます。search_messages と get_message_context を使えば、両方に対応できます。
• 不在中のやり取りを把握する。 グループで不在中に蓄積された 400 件のメッセージをモデルに渡し、 何があったのか尋ねられます。
• 自分の添付ファイルを読む。 download_media を使うと、相手から送られてきた請求書、 領収書、スクリーンショットをダウンロードできるため、モデルが実際に内容を読み取れます。
• 未対応の用件を見つける。 get_last_interaction を使えば、「メッセージをくれたのに、 自分が返信していない相手は誰か？」がわかります。
• 返信の下書きを作成する。 モデルが文面を作成し、送信ゲートで確認すると、 その後に送信されます。
• ほかのあらゆる情報と一緒に WhatsApp を検索する。 同じクライアントにメール、チャット、 カレンダーの MCP サーバーが接続されていれば、「このクライアントから請求書について連絡があったか。 それはどこか？」という質問ひとつで済み、検索を 3 回に分ける必要がありません。 実際のやり取りが WhatsApp にある人にとって、これが実行する理由です。

使うべきでない用途

これを使ってサポートボット、アウトリーチツール、自動応答機能を構築しないでください。 先にメッセージを送ってきていない相手に大量のメッセージを送る行為は、 電話番号が停止されたという報告が最も多い行為です（停止リスクを参照）。 これは、Meta が WhatsApp Business API を提供している用途そのものです。 これは自分のメッセージを扱うための個人用ツールです。 顧客に使えば、電話番号を失うことになります。

MCP クライアントでできること

ツールは 24 個あり、読み取り専用が 14 個、ゲート付きが 10 個です。以下で説明します。

読み取り／検索（制限なし）

ツール	返される内容
list_chats	チャット（1 対 1 およびグループ）。最新のアクティビティ順で、名前やアーカイブ状態で絞り込めます。
get_chat	JID で指定した 1 つのチャット。
list_messages	チャット内のメッセージ。新しいものから順に表示され、任意で期間を指定できます。名前付きの期間（today、yesterday、last_24h、last_7d）、IANA tz を指定した date、または明示的な範囲（Unix 秒、RFC 3339、日付のみ）を渡します。タイムゾーンの計算はサーバーが行います。
search_messages	メッセージ本文の全文検索。チャットを指定することも、全体を検索することもできます。
get_message_context	対象メッセージの直前および直後のメッセージ。
search_contacts	名前または電話番号の一部で連絡先を検索します。
get_last_interaction	JID に関連する最新のメッセージ。
list_group_participants	グループのメンバーの JID。最新情報を取得します。
get_group_info	グループの件名、説明、オーナー、管理者。最新情報を取得します。
get_blocklist	アカウントがブロックしている JID。最新情報を取得します。
get_call_history	通話履歴。新しいものから順に表示され、相手を 1 人に絞り込み、list_messages と同じ期間／日付／tz の形式で期間を指定できます。
download_media	添付メディアをローカルのデータディレクトリにダウンロードします。1 件のメッセージ、複数のメッセージ ID、または期間内のすべてのメディアを指定できます（list_messages と同じ期間／日付／tz の形式を使用し、種類で絞り込むこともできます）。
poll_new_messages	カーソルより後の新しいメッセージを古いものから順に取得します。tail: N を指定すると最新の N 件をすぐに返し、タイムアウトを指定すると新しいメッセージが届くまで最大 240 秒待機します。そのため、チャットを読み直さずにエージェントがアクティビティに応答できます。指定しない限り、自分が送信したメッセージは除外されます。読み取り専用です。応答の送信には引き続き送信ゲートを通す必要があります。
fetch_older_messages	チャットに保存されている最古のメッセージより前のメッセージを電話に要求し、遡って読み取れる範囲を広げます。さらに前のメッセージを取得するには、繰り返し呼び出してページを進めます。
doctor	MCP ツールとして、診断に記載された診断を実行します。

これらのツールがどこまで遡れるかは、このサーバーではなくペアリングされた 電話によって決まります。「履歴全体を検索する」が「ここ数か月を検索する」 という意味になることもあります。制限事項をご覧ください。

どのチャットにアクセスするかは、ユーザーが決めます。デフォルトではすべてのチャットが対象ですが、 許可リストを設定することもできます。詳しくは、 エージェントが読み取り可能なチャットをご覧ください。

送信（ゲートあり — 下記を参照）

ツール	機能
send_message	テキストを送信します。既存のメッセージを引用することもできます。
send_media	許可されたディレクトリにある画像、動画、ドキュメントを、任意のキャプションを付けて送信します。
send_voice_note	許可されたディレクトリにある Ogg Opus（.ogg）ファイルからボイスメッセージを送信します。トランスコードは行わず、ほかの形式は拒否されます。
send_reaction	絵文字でメッセージにリアクションします（空の絵文字を指定すると、以前のリアクションが削除されます）。
edit_message	WhatsApp の編集可能時間内に、自分が送信したメッセージのテキストを編集します。
delete_message	全員のメッセージを削除します（自分のメッセージは常に削除できます。他の人のメッセージはグループ管理者の場合に限り削除できます）。
create_poll	投票（質問と 2 つ以上の選択肢）を作成します。投票結果の読み取りには対応していません。
mark_read	1 件以上のメッセージを既読にします。
schedule_send	テキストまたはメディアの送信を将来の時刻に予約します（最大 30 日先まで。send_at または delay_minutes を指定）。ゲートは予約時に適用されます。信頼されていない宛先の場合は、予約の実行時刻を含め、下書きを作成して確認を求めます。実行時には共有レートリミッターを消費します。予約は再起動後も保持されますが、実行されるのは serve の実行中に限られます（15 分以内の遅延は次回起動時に実行され、それより古い予約は破棄されます）。
list_scheduled	保留中の予約送信を、実行時刻が早い順に一覧表示します。
cancel_scheduled	保留中の予約送信を 1 件キャンセルします。送信を防ぐだけなので、常に許可されます。
block_contact	連絡先をブロックします。常に先に下書きを作成し、信頼されていても自動確定はしません。
unblock_contact	連絡先のブロックを解除します。常に先に下書きを作成し、信頼されていても自動確定はしません。

WhatsApp のデータ（メッセージ、名前、連絡先、キャプション）から作成されるすべてのツール結果には、明示的な未信頼データのバナーが付けられます。これは MCP クライアントが表示しているデータとして扱い、モデルが従うべき指示として扱わないでください。WhatsApp 経由で届く内容によって、アシスタントに何かを指示することはできません。

送信ゲート

これは verygoodplugins/whatsapp-mcp にない機能です。テキスト、メディア、ボイスメモ、リアクション、編集、削除、投票、ブロック、ブロック解除、既読通知など、すべての送信アクションは、モデルに「注意する」よう促すのではなく、サーバーが強制する単一の経路を通ります。

1. まず下書きを作成します。 まだ信頼していない宛先に送信ツールを呼び出しても、何も送信されません。プレビュー（解決された宛先の名前と JID、送信内容の全文）と draft_token が返されます。
2. 確認して確定します。 同じ呼び出しをその draft_token 付きで再実行すると、送信されます。下書きは 5 分後に期限切れになります。再送信した内容に 1 バイトでも違いがあると、トークンは無効になります。
3. 意図的に信頼します。 whatsapp-connect-mcp trust --add <who> を実行すると、連絡先またはグループを信頼済みとして登録できます。<who> には名前、電話番号、または JID を指定します。名前が曖昧な場合は候補が表示され、推測ではなく確認を求められます。信頼済みの宛先への送信は、下書きの作成を経ず、最初の呼び出しで確定します。これは CLI 専用の切り替え機能です。MCP ツールから信頼を付与することはできないため、モデルが信頼設定を利用して下書きの手順を回避することはできません。送信の判断ごとにリストが読み直されるため、実行中の serve プロセスも含め、trust --add／--remove は即座に反映されます。維持したくない信頼付与には、セッション単位の形式を使用できます。whatsapp-connect-mcp trust --session --add <jid> を実行すると、現在の serve プロセスが動作している間だけ宛先の権限が引き上げられます。この設定が config.json に書き込まれることはなく、次に serve を起動すると自動的に消去されます。特定の相手やグループとのやり取りを積極的に下書きしていて、最初の送信を手動で確認済みの場合に使用すると、その宛先への下書きと確認の往復を省略できますが、永続的な信頼付与にはなりません。永続的な信頼設定と同じく CLI 専用であり（MCP ツールから付与することはできません）、ブロック／ブロック解除は引き続き呼び出しごとに下書きが必要です。
4. 常にレート制限が適用されます。 下書きか信頼済みかを問わず、すべての送信で、5 つの送信ツール全体で共有される 1 つのレートリミッターのトークンを消費します。間隔には 5 秒のハード下限があり、どの設定でもこれを短縮できません。レート制限により確定できなかった場合も下書きは有効なままなので、制限が解除されたら同じトークンで同じ呼び出しを再試行してください。

下書きの作成を経ない唯一の例外は mark_read です。既読通知は作成者が記述するコンテンツではないため、常に最初の呼び出しで送信されます（レート制限とゲートは引き続き適用されます）。

送信に添付できるファイル

上記のゲートが許可するのは、宛先 です。送信で指定する ファイル については制限しません。このゲートだけでは、操作されたモデルが、このプログラムで読み取り可能なあらゆるもの（SSH キーやパスワードストアなど）を、すでに信頼済みの宛先に添付できてしまいます。

そのため、送信ファイルは許可リストに登録されたディレクトリに限定されます。デフォルトでは、初回実行時に作成される専用ディレクトリ 1 つだけが対象です。

OS	デフォルトの送信トレイ
Linux	~/.config/whatsapp-connect-mcp/outbox
macOS	~/Library/Application Support/whatsapp-connect-mcp/outbox
Windows	%AppData%\whatsapp-connect-mcp\outbox

送信前にファイルをそこへ移動するか、config.json の media_roots に絶対ディレクトリパスを設定して、許可リストを拡張してください。

{ "media_roots": ["/home/you/Pictures", "/home/you/Documents"] }

パスは確認前に解決されるため、許可されたディレクトリ内のシンボリックリンクは、置かれている場所ではなく、実際のリンク先に基づいて判定されます。リスト外のファイルを指定した送信は、最初の呼び出し時に拒否されます。下書きの発行前、かつレート制限トークンの消費前に拒否され、サーバーが返す他のすべてのエラーと同様、拒否時にパスが示されることはありません。

エージェントが読み取れるチャット

デフォルトでは、クライアントを接続すると、アカウント上のすべてのチャットにアクセスできるようになります。多くの場合、これは意図した範囲を超えています。必要なのは特定のグループでのサポートであって、10年分のやり取りへの継続的なアクセスではありません。

そのため、読み取り可能な範囲を許可リストに限定できます。setup で一度設定するか、後からダッシュボードの clients タブまたは scope コマンドで変更できます。

whatsapp-connect-mcp scope --list                       # what agents can read now
whatsapp-connect-mcp scope --allow [email protected]
whatsapp-connect-mcp scope --deny  [email protected]
whatsapp-connect-mcp scope --all                        # drop the limit again

--allow は、チャットを指定すると同時に制限を有効にします。つまり、1つのチャットを許可するということは、それ以外を制限するということです。--all は制限を無効にしますが、リストは保持されるため、制限を再び有効にしても入力し直す必要はありません。ダッシュボードでは、現在のモードが示された状態で同じ2つのモードが並んでいるので、どちらに切り替える場合もワンクリックです。

制限を有効にすると、次の範囲に適用されます。

• リストにないチャットのメッセージ、検索、コンテキスト、メディア、履歴へのアクセスは拒否されます。拒否メッセージでは、チャットが存在しないふりをするのではなく、スコープ外であることを伝えます。そのため、モデルは再試行せず、要求を止めます。
• すべてのチャットを対象とする質問（グローバル検索、poll_new_messages、通話履歴、連絡先検索）の結果は、許可された範囲に絞り込まれます。連絡先も対象です。エージェントがアドレス帳を引き続き列挙できるなら、制限が保護しようとしている情報がそのまま漏れてしまいます。
• ストアを一度ラップすることで制限を適用するため、現在および将来のすべての読み取りツールが対象になります。

この機能を利用する前に、次の3点を確認してください。

• 制限は各クライアントではなく、サーバーに適用されます。 すべてのクライアントは同じベアラートークンで認証するため、サーバーは Cursor と Claude Desktop を区別できません。すべてのクライアントに同じスコープが適用されます。クライアントごとに異なるスコープを設定するには、まずクライアントごとのトークンが必要です。
• 変更できるのはユーザー本人だけです。 信頼リストと同じルールにより、MCP ツールから config.json に書き込むことはできません。対象自身が範囲を広げられるなら、その制限は名ばかりになってしまいます。
• 許可リストが空の場合、何も読み取れません。すべてが読み取れるわけではありません。 これは setup の3つ目の回答によって設定される状態であり、意図的なものです。そうしなければ、求めていないアクセスが気付かないうちに許可されてしまいます。この状態ではすべての読み取りツールが空の結果を返すため、インストールが壊れているように見えます。そのため check はこの状態を示し、解除方法を説明します。

ダッシュボードには、これらの制限は適用されません。ダッシュボードは、エージェントのものではなく、あなた自身のメッセージを見るための画面です。

この制限が対象とするのは読み取りです。送信は別途送信ゲートによって制御され、チャットが読み取り可能かどうかにかかわらず、送信先ごとに確認を求めます。

verygoodplugins/whatsapp-mcp との比較

現在、最もよく知られている代替手段は動作しますが、導入が面倒で、送信時の安全対策がありません。

	verygoodplugins/whatsapp-mcp	whatsapp-connect-mcp
必要なランタイム	Go と Python、2つのプロセス	静的バイナリ1つ、前提条件なし
インストール	リポジトリをクローンし、ブリッジを手動で実行し、クライアント設定を手動で編集して再起動	1行のインストールコマンド → setup ウィザードがクライアントに自動設定
ペアリング	自分で開いたままにするターミナル上の QR コード	ウィザードで管理する QR ペアリング。セッションはバイナリが監視
送信時の安全対策	なし — モデルはすぐに送信できます	下書き優先の送信ゲート + レート制限
プロンプトインジェクション対策	なし	WhatsApp 由来の結果すべてに信頼できないデータのバナーを表示
読み取り範囲	常にすべてのチャット	すべてのチャット、またはセットアップ時に選択して後から編集できる許可リスト
診断	なし	doctor（CLI サブコマンドおよび MCP ツール）、サニタイズ済みの出力
配布方法	Git クローンのみ	GitHub Releases、インストールスクリプト、MCP Registry、MCPB バンドル、npm ラッパー

BANリスク

Metaは、サードパーティ製クライアントを独立した2つの方法で検出します。そのうち、動作に関するものは1つだけです。

1. クライアントを識別できます。 リンク済みデバイスは登録時に自身の情報を通知します。whatsmeowのデフォルトでは、プラットフォーム種別が不明なまま、OS文字列としてwhatsmeowを通知します。これは、ペアリングのペイロードだけを読み取れば、公式クライアントと区別できます。このプロジェクトではこれを上書きし、代わりにChromeブラウザーの識別情報を通知します（internal/bridge/clientinfo.go）。これは、リンク済みデバイスの画面でこのデバイスに対してスマートフォンに表示される情報でもあります。

この上書きを問題の解決策と誤解しないでください。最も単純な検査は回避できますが、根本的な問題は解決しません。serveとsetupは接続前にWhatsApp Webの報告バージョンを更新するため、バージョンとそこから生成されるビルドハッシュは、ビルド時に同梱されていたバージョンではなく実際のリリースに追随します。しかし、ユーザーエージェントには依然としてwhatsmeowのプレースホルダーである通信事業者とメーカーのフィールドが含まれ、通信上のセッションの挙動もChromeではなくwhatsmeowのものです。実際のChromeブラウザーを動かし、本物のフィンガープリントを使うwhatsapp-web.jsのユーザーにも、以下で説明する警告が届いています。このことから、通知される識別情報が決定的なシグナルではなかった可能性がうかがえます。また、識別情報はペアリング時に送信されるため、変更してもすでにペアリング済みのセッションには何の効果もありません。既存のセッションは、再度ペアリングするまで登録時の情報を保持します。

2. 挙動。 報告されている引き金を、発生頻度のおおよその順に挙げます。先にメッセージを送ってきたことのない相手へのメッセージ送信、高い送信速度、ペアリング直後の大量送信、同じメッセージの繰り返し送信、自動化されたステータス投稿、頻繁な再接続ループです。

気がかりなのは、公開されている情報から、主な要因は（1）だと考えられることです。whatsmeow#810では、2025年5月の「アカウントがリスクにさらされている可能性があります」という警告が相次いだ際に、メッセージを一度も送信せず、接続していただけのアイドル状態のアカウントや、数週間接続を切断していたアカウントにも警告が届いたとユーザーが報告しています。このイシューは2026年7月にnot plannedとしてクローズされました。まったく異なる実装であるwhatsapp-web.jsのユーザーにも警告が届いています。同じスレッドで、Baileysのメンテナーは反対に、これは「主に挙動の問題」だと主張しています。どちらなのかは誰も明らかにできず、スレッドは回答のないままクローズされました。

つまり、ここにある送信ゲートとレートリミッターは（2）への実質的な緩和策ですが、（1）には何の効果もありません。入手可能な情報から判断すると、適切に振る舞うことで変わるのは、順番が来るかどうかではなく、いつ順番が来るかです。

ペアリングする前に読んでおく価値のある報告を、情報の新しさを判断できるよう日付付きで示します。

報告	作成日	最終更新
whatsmeow#810 — 「アカウントがリスクにさらされている可能性があります」という警告の波	2025年5月	2026年7月（クローズ）
Baileys#2309 — 自動化されたステータス投稿後の永久BAN	2026年1月	2026年5月（オープン）
Baileys#1869 — 3年以上稼働しているインスタンスで、1週間に5回の利用停止	2025年10月	2026年5月

ベンダーのブログにあるBAN統計、たとえば「12か月以内に68％の企業がBAN」「返信のない状態が30日続くと累積判定」といった主張は、有料のBusiness API再販業者による、出典のないマーケティングとして扱ってください。一次情報による裏付けはなく、そのため、このドキュメントにもいずれの数字も記載していません。

制限事項（明示）

• 電話番号が利用停止になる可能性があり、このプロジェクトでは防げません。
  利用停止のリスクをご覧ください。これが最も重要な制限事項です。
• 履歴の取得範囲は、ペアリングした電話で決まります。 すべての WhatsApp Web クライアントと同様に、ペアリングした電話が、このサーバーに同期するチャット履歴の範囲を制御します。電話から渡される以上の履歴を取得する設定はありません。setup --full-history は、既定の数か月分ではなく、プロトコルで許可される限り多くの履歴を要求しますが、設定ではなくリクエストです。また、ペアリング時にのみ適用されます。すでにペアリング済みのインストールでは、fetch_older_messages ツールを使うと、再ペアリングせずに電話へ単一のチャットの履歴をさらに要求できます。いずれも、電話がより少ないデータ、または何も返さないことを選べるリクエストであり、電話自体が削除したメッセージは復元できません。
• ボイスメモの入力形式は Ogg Opus である必要があります。 send_voice_note はトランスコードを行いません。元の音声がすでに .ogg／Opus 形式でない場合は、先に変換してください（例：ffmpeg -i in.mp3 -c:a libopus out.ogg）。
• 発信には対応していません。 通話履歴の読み取りには対応していますが、通話の開始には対応していません。
• 一度にペアリングできる電話番号は1つです。 電話番号ごとにメッセージ、信頼リスト、読み取り可能なチャット、スケジュールが個別に保持されるため、切り替えても問題なく、データが引き継がれることはありません。ただし、一度にリンクできるのは1つだけです。それぞれ異なる MCP クライアントに紐づく2つのアカウントを同時に稼働させるには、サーバーが2つ必要であり、現時点では対応していません。
• whatsmeow は WhatsApp のプロトコル変更に追従します。逆ではありません。 WhatsApp 側の変更により、whatsmeow（ひいてはこのプロジェクト）が対応するまで、ペアリングや送信ができなくなる場合があります。

データとプライバシー

セッションキー、メッセージ、メディア、連絡先、通話履歴など、すべてのデータは、このプログラムのデータディレクトリ内にあるローカルの SQLite データベースに保存されます。このサーバーから、メッセージ、連絡先、メディアに関する情報が外部に送信されることはありません。

WhatsApp への接続自体を除き、外部へのネットワーク接続は2つだけです。どちらもベストエフォートで、2秒後にタイムアウトし、メッセージの内容、JID、電話番号、セッション認証情報を送信することはありません。

• doctor／check は GitHub の公開リリース API に問い合わせ、このプログラムに新しいバージョンがあるか確認します。GitHub に接続できなくても、チェックがブロックされたり失敗したりすることはありません。
• serve と setup は接続前に、現在の WhatsApp Web クライアントのバージョンを web.whatsapp.com から取得します。これにより、このクライアントが報告するバージョンは、ビルド時に同梱されたものではなく、実際のリリースに追従します。取得に失敗した場合はその旨が報告されますが、処理は続行されます。古いバージョンでも接続できます。

データディレクトリ：

OS	パス
Linux	~/.config/whatsapp-connect-mcp
macOS	~/Library/Application Support/whatsapp-connect-mcp
Windows	%AppData%\whatsapp-connect-mcp

その中では、WhatsApp アカウントに属するデータはすべて各アカウントの電話番号の下に保存され、マシンに属するデータはすべて最上位に配置されます。

config.json              rate limits, outbox roots — shared
outbox/                  files a send may attach — shared
session.db               the current pairing
accounts/<number>/
  messages.db            that number's messages
  media/                 that number's downloaded attachments
  backups/               that number's snapshots
  account.json           that number's trust list and readable chats
  schedules.json         that number's pending scheduled sends

別の電話番号をペアリングすると、その番号専用のディレクトリが作成されます。最初の番号を再びペアリングすると、履歴、信頼リスト、設定はすべて以前の状態のままです。既存のインストールは次回の実行時にこの構成へ移行され、ファイルを書き換えるのではなく、名前を変更して移動されます。

診断

whatsapp-connect-mcp check

doctor MCP ツールが提供するものと同じチェックを実行します。セッションのペアリング／接続状態、イベントフローの稼働状況（接続済みのセッションで30分を超えて WhatsApp イベントを受信していない場合は警告します。ソケットは正常に見えても、取り込みがひそかに停止している状態です）、メッセージデータベースの整合性、注入された MCP クライアント設定、チャットの範囲（有効化されているものの空の状態も含みます。この場合、すべての読み取りツールが正しく何も返さず、インストールが壊れているように見えます）、データディレクトリの権限（POSIX）、および上記のバージョンチェックを確認します。すべての検出結果はサニタイズされます。ステータス行に JID、電話番号、メッセージの内容、ファイルシステムのパスが表示されることはありません。クライアント設定に問題がある場合は、ディスク上のパスではなく、クライアント名が表示されます。

ダッシュボード

whatsapp-connect-mcp dashboard [--port n]

serve --http とともに提供される小さなウェブダッシュボードのワンタイムログインリンクを表示し（開こうとします）。接続状態、ストアの行数、check が表示するものと同じ doctor の診断結果を数秒ごとに更新して表示します。このリンクは HTTP トランスポートの既存のベアラートークンをセッション Cookie と交換するため、新たに設定したり、信頼したりするものはありません。

ダッシュボードがリッスンするのは、同じポートを共有する HTTP トランスポートとまったく同様に、常にループバックのみです。serve --http がすでに実行されている必要があり、ほかのマシンからページにアクセスすることはできません。セッションの有効期限が切れたら（ほとんどの場合、サーバーの再起動時）、いつでも dashboard コマンドで再度ログインしてください。表示されたトークンがサーバーログに書き込まれることはありません。

セッションが未ペアリングの場合、ダッシュボードの「ペアリング」タブでは QR コードがブラウザー上に表示されます。そこでペアリングを開始し、WhatsApp の「リンク済みデバイス」＞「デバイスをリンク」からスキャンすればよく、ターミナルは必要ありません。WhatsApp 側でログアウトした後の再ペアリングにも対応します。セッションがペアリング済みの場合、同じタブに「リンク解除」が表示されます。これにより WhatsApp のサーバー上でサーバーからログアウトし（スマートフォンの「リンク済みデバイス」一覧から表示が消えます）、QR コードを再表示します。logout コマンドでもターミナルから同じ操作ができます。ローカルのセッションを削除するだけで、WhatsApp には通知しない remove とは異なります。

「クライアント」タブには、このマシンで検出された MCP クライアントがすべて表示されます。インストールされているか、このサーバーが追加されているか、エントリポイントの場所が一覧で確認でき、ワンクリックでエントリを追加または削除できます。そのため、doctor が壊れていると判定した設定も、ターミナルを開かずに修正できます。同じタブには、接続中のエージェントが読み取れるチャットを制限する 読み取り可能なチャット もあります（エージェントが読み取れるチャットを参照）。

「信頼」タブでは、信頼する連絡先の一覧を表示、編集できます。trust コマンドが管理するものと同じ config.json なので、変更は実行中のサーバーに即座に反映されます。「読み取り可能なチャット」と同様に、連絡先やグループの 名前 または 電話番号 を指定でき、生の JID だけを指定する必要はありません。名前が複数の相手に一致した場合は選択できるよう一覧表示され、選択するまで何も書き込まれません。「スケジュール」タブには保留中の予約送信が一覧表示され、キャンセルできます。「下書き」タブには、エージェントが提案し、承認を待っている送信が一覧表示されます。承認すると、表示された内容そのままが送信され（通常どおりレート制限が適用されます）、破棄すると削除されます。ダッシュボードとエージェント自身による再試行のどちらが先に処理しても、下書きが確定されるのは最大 1 回です。「バックアップ」タブでは、下記の backup コマンドとまったく同じスナップショットをワンクリックで作成できます。

バックアップ

whatsapp-connect-mcp backup [--dest path]

ペアリング済みアカウントのメッセージデータベースの一貫性のあるスナップショットを、<data-dir>/accounts/<number>/backups/messages-<timestamp>.db に書き込みます（--dest でカスタムパスを指定できます）。番号ごとに個別にバックアップされるため、誰かに渡すスナップショットには、そのアカウントのデータだけが含まれます。 バックアップは単独で完全に使用可能な SQLite データベースであり、セッションや設定のコピーではなく、メッセージのみが含まれます。スマートフォンのバックアップとは異なり、serve の実行中でも安全に backup スナップショットを作成できます。SQLite の WAL モードとビジータイムアウトにより、一貫性が保証されます。

メッセージ履歴だけは、ほかの方法では復元できません。必要であればセッションは再ペアリングできますが、スマートフォンから取得したメッセージは、スマートフォンが記憶している間だけスマートフォンに残ります。通常は数か月です。cron、systemd タイマー、または Windows のタスク スケジューラを使った定期的な自動バックアップが、メッセージを失わないための最も簡単な備えです。

その他のコマンド

whatsapp-connect-mcp setup [--full-history]  # pair (again) and configure MCP clients
whatsapp-connect-mcp status                  # pairing state, row counts, injected clients
whatsapp-connect-mcp clients [--remove]      # list or uninject MCP client entries
whatsapp-connect-mcp trust [--session] [--add who|--remove who|--list]
whatsapp-connect-mcp scope [--allow who|--deny who|--all|--list]
                                             # limit which chats agents may read
whatsapp-connect-mcp serve [--http addr]     # run the MCP server directly (stdio by default)
whatsapp-connect-mcp service <install|uninstall|restart> [--http addr]
                                             # manage a background serve --http service (macOS/Linux/Windows)

--http にはベアラートークンとループバックの Host が必要です。 初回使用時に 256 ビットのトークンが生成され、データ ディレクトリ内の .http-token に所有者のみがアクセスできる状態で書き込まれ、一度だけ表示されます。これをクライアントの Authorization: Bearer <token> ヘッダーに設定してください。すべてのリクエストはループバックの Host（localhost、127.0.0.1、[::1]）宛てである必要もあります。これにより、ブラウザー内のウェブページが DNS をループバックアドレスに再バインドしてサーバーにアクセスするのを防ぎます。 それでも 127.0.0.1 にバインドしてください。トークンはポートへのアクセスを防ぎますが、パブリックインターフェースにバインドするとネットワーク全体に公開されます。やむを得ない場合は、前段に独自のアクセス制御（リバースプロキシ、VPN、ファイアウォールルール）を設置してください。

更新

更新で置き換わるのはバイナリだけです。ペアリング、メッセージ履歴、 信頼リスト、クライアントに注入された設定はすべてデータディレクトリに保存され、 更新後もそのまま残ります。インストール時と同じ方法を使ってください。どの方法でも、 新しいバイナリは古いバイナリと同じパスに配置されるため、クライアントの 設定は引き続き機能します。

# macOS / Linux — the install script always fetches the latest release
curl -fsSL https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/idle-sync/whatsapp-connect-mcp/main/scripts/install.ps1 | iex

# npm global install
npm update -g whatsapp-connect-mcp

# npx without an install — @latest bypasses npx's cached copy
npx whatsapp-connect-mcp@latest setup

次に、バイナリを実行しているものを再起動してください。stdio クライアントでは、MCP クライアントが次のセッションを開始したときに新しいバージョンが使われます（クライアントアプリを再起動してください）。http トランスポートの場合は、serve を再起動してください。service install でインストールしたサービスの場合は、次のとおりです。

whatsapp-connect-mcp service restart

常時稼働するサービスは自動で再実行されないため、再起動するまでは古いバージョンが実行され続けます。

リリースページを確認する必要はありません。whatsapp-connect-mcp check と doctor MCP ツールは、実行のたびに稼働中のバージョンと最新リリースを比較し、異なる場合は両方のバージョンを示して警告します。

アンインストール／リセット

• whatsapp-connect-mcp remove はローカルの WhatsApp セッションを削除します（このサーバーとのローカルなペアリングを解除します。次回の setup では再度ペアリングが必要です）。これはローカルだけの操作です。WhatsApp のサーバーには通知されないため、電話では自分でリンクを解除するまで、リンク済みデバイスの一覧にこのデバイスが表示され続けます。操作の前に、yes の入力を求めます。
• whatsapp-connect-mcp reset は remove のすべての処理に加え、現在のアカウントだけでなく、このインストールでペアリングしたすべてのアカウントの保存済みメッセージ、メディア、設定を削除します。新規インストール時の状態に戻す完全消去です。こちらも yes の入力を求めます。
• whatsapp-connect-mcp clients --remove は、追加先の MCP クライアント設定からこのプログラムのエントリーを削除します。ペアリング済みセッションには影響しません。
• バイナリ自体を削除するには、インストーラーが配置した場所（~/.local/bin、%LOCALAPPDATA%\Programs\whatsapp-connect-mcp、または npx のキャッシュ先）から削除し、上記のデータディレクトリも削除してください。

ライセンス

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