whatsapp-mcp の機能
whatsapp-mcp は、MCP 対応 AI エージェントが WhatsApp メッセージを読み取り、検索できる小規模なサーバーです。ご自身の Cloudflare アカウント上で実行され、WhatsApp Web 形式のリンク済みデバイスとしてスマートフォンに接続します。
初回設定後は、Claude Code、Claude Desktop、その他の MCP アプリケーションなどのクライアントから、次のような質問に回答できます。
- フライトについて Dana は何と言っていましたか？
- すべてのチャットから、リースに言及しているメッセージを見つけてください。
- 今週、家族グループで見逃した内容を要約してください。
このサーバーは意図的に読み取り専用となっています。メッセージの収集、検索、表示はできますが、WhatsApp メッセージを送信することはできません。
システムの仕組み
情報の正式な管理元はスマートフォンです。Cloudflare のデプロイメントはリンク済みデバイスとして動作し、データの同期が必要なとき、またはアカウントをペアリングするときだけ WhatsApp に接続します。
エージェントが情報を要求すると、保存済みのコピーが 10 分以上古い場合、サーバーは WhatsApp から保留中の更新を取得します。スケジュールされた取得も 1 日に 1 回実行されます。メッセージの収集後、サーバーは再び切断されます。スマートフォンは通常どおり動作し、通知も引き続き受信します。
メッセージは、アカウント内の Cloudflare Durable Object にある SQLite データベースに保存されます。サーバーがメッセージ履歴を外部ストレージサービスに送信することはありません。
前提条件
インストール前に、次のものを準備してください。
- Workers Paid プランの Cloudflare アカウント。
- Node.js 20 以降。
- リンクする WhatsApp アカウントが設定されたスマートフォン。
- Claude Code や Claude Desktop などの MCP クライアント。
大規模な WhatsApp 履歴のインポートでは、デフォルトの CPU 制限を超える可能性があるため、Workers の有料プランが必要です。リポジトリでは wrangler.jsonc でこの制限を引き上げており、Cloudflare は高い制限を利用するために有料プランを要求しています。
インストールとデプロイ
リポジトリをクローンし、依存関係をインストールして、必要な KV namespace を作成し、所有者パスワードを保存してから Worker をデプロイします。
git clone https://github.com/finereli/whatsapp-mcp
cd whatsapp-mcp
npm install
npx wrangler kv namespace create OAUTH_KV
npx wrangler secret put OWNER_PASSWORD
npm run deployパスワードは 12 文字以上である必要があります。デプロイが完了すると、Wrangler は https://whatsapp-mcp.your-name.workers.dev のような URL を表示します。その URL を開いて設定を続行してください。
カスタムドメインを使用する場合は、wrangler.jsonc の末尾にあるコメントに従ってください。
WhatsApp アカウントをリンクする
デプロイページに、残りの設定手順が表示されます。
- WhatsApp をリンクするオプションを選択します。
- スマートフォンで WhatsApp を開き、設定、リンク済みデバイス、デバイスをリンクの順に進みます。
- サーバーに表示された QR コードをスキャンします。同じスマートフォンを使用していて画面をスキャンできない場合は、電話番号によるペアリングオプションを使用してください。
- 初回のリンクで、WhatsApp が新しいデバイスに提供する履歴のインポートが完了するまで待ちます。
ページにはインポートの進行状況が表示されます。処理中にページを閉じても問題ありません。新しくリンクされたデバイスに提供する履歴を WhatsApp が決定するため、初回のインポートに過去のメッセージがすべて含まれるとは限りません。
MCP クライアントを接続する
Claude Code で、/mcp エンドポイントを使用してデプロイ済みサーバーを登録します。
claude mcp add --transport http whatsapp https://your-url/mcp次に Claude Code で /mcp を実行し、所有者パスワードでサインインします。その他の MCP クライアントも同じ URL で設定してください。
https://your-url/mcp認証が完了したら、エージェントにチャットの一覧表示、メッセージの取得、履歴の検索を依頼できます。
利用可能なツール
MCP サーバーは、ローカルに保存されたメッセージの読み取りと管理に特化したツールを提供します。
list_chatsは、最新のチャットから順に一覧表示します。名前または番号による任意の絞り込みにも対応しています。get_messagesは 1 つのチャットからメッセージを読み取り、日付による前後方向のページングに対応しています。search_messagesは、すべてのチャットまたは選択したチャット内で全文検索を実行します。unnamed_chatsは、電話番号だけで識別されているチャットを見つけます。最もやり取りの多いチャットを優先し、相手からの最新メッセージを表示します。set_contact_namesは電話番号の名前を保存し、グループチャットでも正しく表示できるようにします。sync_nowは新しいメッセージを直ちに取得します。link_statusは、アカウントのリンク状態、最終同期日時、保存されているデータ量を報告します。relinkは現在のリンクを削除し、ペアリング処理を再開します。保存済みのメッセージは引き続き利用できます。
読み取りツールは、保存済みのコピーが 10 分以上古い場合、自動的に先に同期します。そのため、クエリごとに sync_now を手動で呼び出さなくても、自然言語で依頼できます。
電話番号だけで表示されるチャットを解決する
WhatsApp がすべてのリンク済みデバイスに連絡先名を提供するとは限らないため、一部のチャットは電話番号で表示されます。これは、一度限りの会話や、WhatsApp の連絡先に保存されていない相手でよく発生します。
エージェントに次のように依頼してください。
名前のないチャットの名前を見つけてください。エージェントは unnamed_chats を呼び出し、すでに利用している連絡先連携サービスの情報と番号を照合して、set_contact_names を通じて一致した名前を登録できます。たとえば、Google Contacts や Gmail のコネクタから一致する名前を取得できる場合があります。サーバー自体が連絡先サービスにログインすることはありません。
保存した名前は電話番号に関連付けられるため、グループでの会話でも使用できます。一致する連絡先がない場合、一部の番号は名前のないままになります。
メディアとメッセージ履歴を理解する
メディアファイルはダウンロードされません。画像、ボイスメッセージ、ドキュメントは、[image] や [voice note 12s] などのラベルで表されます。WhatsApp がキャプションを提供する場合は保持されますが、ボイスメッセージは文字起こしされません。
最初のリンクでは、WhatsApp が送信することを選択した履歴がインポートされます。通常、履歴はリンクごとに一度だけ配信されます。インポートが不完全な場合は、再リンクして追加のインポートを要求できます。その際、すでに保存されているメッセージは維持されます。取り込み処理は冪等になるよう設計されているため、再インポートによって意図的に重複行が作成されることはありません。
アカウントを再リンクする
WhatsApp でデバイスが削除されたと報告された場合や、ペアリング手続きをやり直したい場合は再リンクしてください。エージェントに relink の実行を依頼するか、/setup を開いて Unlink and scan again を選択します。
指示が表示されたら新しい QR コードをスキャンしてください。保存済みのメッセージは保持され、新しいリンクによって不足している履歴を補完できます。
高度な設定
デフォルトのデプロイではパスワード認証が使用されます。主な設定値は次のとおりです。
OWNER_PASSWORD：所有者パスワード。最小長は 12 文字です。OWNER_EMAIL：ログインサービスモード使用時に許可される唯一のメールアドレスです。OPERATOR_NAME：プライバシーページに表示する任意の名前です。DEFAULT_COUNTRY_CODE：エージェントが国番号なしで番号を保存する際に使用される、数字のみの国番号です。LOGIN_ORIGIN：デプロイをログインサービスモードに切り替えます。ALLOWED_ORIGINS：ログインサービストークンで許可されるオリジンです。PIN：x-pinヘッダーによる保護されたデバッグルートを有効にする、任意の 32 文字以上の値です。OAUTH_KVとWA：アプリケーションが使用する KV および Durable Object のバインディングです。
ドメイン、KV ID、メールアドレスなど、デプロイ固有の値は gitignore 対象の wrangler.local.jsonc ファイルに保存してください。ローカル設定をデプロイするには、次を実行します。
npm run deploy:local同期の問題をデバッグする
PIN を設定すると、サーバーに保護された診断エンドポイントが用意されます。x-pin ヘッダーに PIN を指定してください。
/debugには、セッションフェーズ、リンク状態、件数、最近のセッションイベントが表示されます。/debug/pullは同期を直ちに開始します。/debug/chats?q=、/debug/messages?chat=、/debug/search?q=、/debug/typesでは保存されたデータを確認できます。/debug/unnamedにはunnamed_chatsが返したチャットが表示されます。/debug/sql?q=はストアに対して読み取り専用のSELECTクエリを 1 件実行します。/debug/logoutは再リンクと同等の処理を実行します。
デプロイが成功した後の有用な確認手順は、/debug でセッションがアイドル状態かつアカウントがリンク済みであることを確認し、/debug/pull を実行してから、チャット一覧表示、メッセージ取得、全文検索、名前のないチャットの処理、連絡先名の設定をテストすることです。
ローカルで開発する
ローカル開発では、十分に長いパスワードを含む .dev.vars ファイルを作成し、Worker を起動します。
OWNER_PASSWORD=your-12-character-or-longer-password
npm run devローカル開発では、空のストレージを持つ別の Durable Object が使用されます。サインインフローを実行して実際の QR コードを表示できますが、ローカルで電話をリンクすると、別のリンク済みデバイスが作成されます。
コード変更を提出する前に、次を実行してください。
npm run typecheck
npm testテストスイートは、Node 22.13 以降に組み込まれている SQLite を使ってストアコードを実行します。その SQLite 環境では全文検索が対象外のため、デプロイ後にも検索をテストしてください。
重要なセキュリティとプラットフォーム上の考慮事項
このプロジェクトは公式の WhatsApp 統合ではありません。WhatsApp は個人メッセージを読み取る API を提供しておらず、このプロジェクトはオープンソースの Baileys ライブラリを通じて WhatsApp Web と同じプロトコルを使用します。この利用は WhatsApp の規約に違反する可能性があります。自分のアカウントでのみ使用し、読み取り専用のリンク済みデバイスであれば実際のリスクは低いものの、ゼロではないことを理解してください。
1 つのデプロイは、1 人のユーザーと 1 つの WhatsApp アカウントで使用することを想定しています。各デプロイには完全なメッセージ履歴とアカウントの有効なログイン情報が保存されるため、1 つを共有するのではなく、ユーザーごとに別々のデプロイを実行してください。
メッセージは Durable Object の SQLite ストレージ内に保存されますが、デプロイ認証情報または所有者認証にアクセスできる人は、保存された履歴にアクセスできる可能性があります。パスワード、Cloudflare アカウント、シークレット、デバッグ PIN は厳重に保護してください。
まとめ
whatsapp-mcp は、WhatsApp のリンク済みデバイスプロトコルと MCP クライアントをつなぐ実用的な橋渡しを提供します。Cloudflare にデプロイして一度スマートフォンをリンクし、エージェントを /mcp に接続すれば、search_messages、get_messages、set_contact_names などのツールを使って自分のメッセージアーカイブを検索できます。読み取り専用の設計、非公開の Durable Object ストレージ、スケジュールされた同期、明示的な再リンク手順により、デプロイを自分で管理しながら個人メッセージを検索する用途に適しています。