finereli/whatsapp-mcp

A read-only MCP server that lets your AI agent search and read your own WhatsApp messages. Use it free at whatsapp.finereli.com, or run your own copy on Cloudflare.

概要

whatsapp-mcpは、AIエージェント（Claude Codeなど）があなたのWhatsAppチャットの内容を読み取り、検索できるようにする小さなセルフホスト型サーバーです。Cloudflare Workersサービスとして実行され、Durable Object内のSQLiteデータベースにメッセージを保存し、エージェントが呼び出せるシンプルなMCP (Message-Control-Protocol) エンドポイントを公開します。

仕組み

リンク – WhatsApp Webにデバイスを追加するのと同様に、Web UIからQRコードをスキャン（または電話番号方式を使用）します。サーバーはリンクされたデバイスとなり、WhatsAppが新しいデバイスに対して提供するチャット履歴を取得します。
ストレージ – すべてのメッセージ、チャットメタデータ、全文検索インデックスは、Durable Object内のSQLite DBに保持されます。データが外部に送信されることはありません。
取得 – 1日1回（またはオンデマンドで）、サーバーがWhatsAppに再接続し、前回の取得以降に届いた新しいメッセージを取得してDBを更新し、切断します。スマートフォンは通常通り動作し続けます。
エージェントのアクセス – AIエージェントは、MCPツールセット（チャット一覧、メッセージ取得、検索など）を使用して /mcp エンドポイントと通信します。サーバーはまずDBが最新であることを確認し（10分以上経過していれば取得）、要求されたデータを返します。

主な機能 (MCPツール)

ツール	機能
`list_chats`	最近のアクティビティ順にチャットを返し、名前/番号によるフィルタリングが可能です。
`get_messages`	日付によるページネーションを使用して、単一のチャットからメッセージを取得します。
`search_messages`	すべてのチャットまたは特定のチャット内で全文検索を行います。
`unnamed_chats`	電話番号のみ（保存された連絡先名がない）のチャットを一覧表示します。
`set_contact_names`	電話番号にカスタム名を保存します。この名前は今後のクエリで使用されます。
`sync_now`	新しいWhatsAppメッセージの即時取得を強制します。
`link_status`	デバイスがリンクされているか、前回の取得時間、ストレージサイズを表示します。
`relink`	デバイスのリンクを解除し、新しいQRコードをスキャンできるようにします。既存の保存済みメッセージは保持されます。

セットアップ手順 (概要)

前提条件 – Workersの有料プランに加入しているCloudflareアカウント、Node 20+、WhatsAppがインストールされたスマートフォン。
クローンとインストール – git clone … && npm install。
KV名前空間の作成 – npx wrangler kv namespace create OAUTH_KV を実行し、出力されたIDを wrangler.jsonc に貼り付けます。
パスワードの設定 – npx wrangler secret put OWNER_PASSWORD (12文字以上)。
デプロイ – npm run deploy。Wranglerが https://whatsapp-mcp.your-name.workers.dev のようなURLを表示します。
WhatsAppのリンク – URLを開き、QRコードをスキャン（または電話番号オプションを使用）します。最初のインポートには時間がかかる場合があります。
エージェントの接続 – Claude Codeで claude mcp add --transport http whatsapp https://your-url/mcp を実行し、設定したパスワードで /mcp コマンドを使用します。

重要な制限とリスク

非公式 – WhatsApp Webと同じリバースエンジニアリングされたプロトコル（Baileysライブラリ経由）を使用しています。これはWhatsAppの利用規約に違反します。読み取り専用デバイスとしての実用的なリスクは低いですが、ゼロではありません。
読み取り専用 – メッセージを送信する機能はありません。サーバーは意図的に送信APIを公開していません。
単一ユーザーのみ – 各デプロイは1つのWhatsAppアカウントと所有者パスワードに紐付いています。マルチユーザーサポートにはコードの変更が必要です。
メディアのダウンロード不可 – 画像やボイスメモなどは [image] のようなプレースホルダーとして表示され、取得や文字起こしは行われません。
連絡先名 – 保存されていない連絡先とのチャットは電話番号として表示されます。エージェントは unnamed_chats を呼び出し、次に set_contact_names を呼び出して読みやすい名前を付ける必要があります。
Cloudflare有料プラン – 大規模な履歴のインポートには高いCPU制限が必要であり、これは有料のWorkersプランでのみ利用可能です。
潜在的な不具合 – サーバーはリバースエンジニアリングされたプロトコルに依存しているため、将来のWhatsAppのアップデートにより動作しなくなる可能性があります。

想定される用途

個人のコンテキストを必要とするAIアシスタントを構築する開発者（例：「友人がフライトについて何と言っていたか？」）。
データをサードパーティサービスではなく、自身のCloudflareアカウント内に保持したいプライバシー意識の高いユーザー。
LLM駆動のパーソナルエージェントを実験している研究者。

ライセンス

MIT – コードを自由に利用、修正、デプロイできます。