WhatsApp MCP Server

WhatsApp MCP サーバー

これは WhatsApp 用の Model Context Protocol（MCP）サーバーです。

このサーバーを使うと、個人の WhatsApp メッセージ（画像、動画、ドキュメント、音声メッセージを含む）を検索して読み取ったり、連絡先を検索したり、個人またはグループにメッセージを送信したりできます。また、画像、動画、ドキュメント、音声メッセージなどのメディアファイルも送信できます。

whatsmeow ライブラリを使用して、Whatsapp web マルチデバイス API 経由で個人の WhatsApp アカウントに直接接続します。すべてのメッセージは SQLite データベースにローカル保存され、エージェントが（ユーザーの管理下にある）ツールを通じてアクセスした場合にのみ、LLM（Claude など）に送信されます。

Claude に接続した場合にできることの例を示します。

このプロジェクトや、私が取り組んでいる他のプロジェクトの最新情報を受け取るには、こちらからメールアドレスを登録してください

注意： 多くの MCP サーバーと同様に、WhatsApp MCP も致命的な三要素の影響を受けます。つまり、プロンプトインジェクションによって個人データが流出する可能性があります。

インストール

前提条件

• Go
• Python 3.6+
• Anthropic Claude デスクトップアプリ（または Cursor）
• UV（Python パッケージマネージャー）。curl -LsSf https://astral.sh/uv/install.sh | sh を実行してインストールします
• FFmpeg（任意） - 音声メッセージを使う場合にのみ必要です。再生可能な WhatsApp 音声メッセージとして音声ファイルを送信するには、ファイルが .ogg Opus 形式である必要があります。FFmpeg がインストールされている場合、MCP サーバーは Opus 形式以外の音声ファイルを自動的に変換します。FFmpeg がない場合も、send_file ツールを使って音声ファイルをそのまま送信できます。

手順

1. このリポジトリをクローンします

   git clone https://github.com/lharries/whatsapp-mcp.git
   cd whatsapp-mcp
   

2. WhatsApp ブリッジを起動します

   whatsapp-bridge ディレクトリに移動し、Go アプリケーションを実行します。

   cd whatsapp-bridge
   go run main.go
   

   初回の実行時には、QR コードのスキャンを求められます。認証するには、WhatsApp モバイルアプリで QR コードをスキャンしてください。

   約20日後に、再認証が必要になる場合があります。

3. MCP サーバーに接続します

   以下の JSON をコピーし、適切な {{PATH}} の値を設定します。

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Claude の場合、これを claude_desktop_config.json として、Claude Desktop の設定ディレクトリに保存します。

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Cursor の場合、これを mcp.json として、Cursor の設定ディレクトリに保存します。

   ~/.cursor/mcp.json
   

4. Claude Desktop / Cursor を再起動します

   Claude Desktop を開くと、WhatsApp が利用可能な連携機能として表示されます。

   または Cursor を再起動してください。

Windows との互換性

このプロジェクトを Windows で実行する場合、go-sqlite3 をコンパイルして正しく動作させるには、CGO を有効にする必要があることに注意してください。Windows では既定でCGO が無効になっているため、明示的に有効にし、C コンパイラをインストールする必要があります。

動作させる手順：

1. C コンパイラをインストールします
   Windows 用の C コンパイラのインストールには、MSYS2 の使用をおすすめします。MSYS2 をインストールしたら、ucrt64\bin フォルダーを PATH に追加してください。
   → 詳しい手順についてはこちらをご覧ください。

2. CGO を有効にしてアプリを実行します

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go
   

この設定を行わないと、次のようなエラーが発生する可能性があります。

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

アーキテクチャの概要

このアプリケーションは、次の2つの主要コンポーネントで構成されています。

1. Go WhatsApp ブリッジ（whatsapp-bridge/）：WhatsApp の Web API に接続し、QR コードによる認証を処理して、メッセージ履歴を SQLite に保存する Go アプリケーションです。WhatsApp と MCP サーバーをつなぐブリッジとして機能します。

2. Python MCP サーバー（whatsapp-mcp-server/）：Model Context Protocol（MCP）を実装する Python サーバーです。Claude が WhatsApp のデータを操作したり、メッセージを送受信したりするための標準化されたツールを提供します。

データストレージ

• すべてのメッセージ履歴は、whatsapp-bridge/store/ ディレクトリ内の SQLite データベースに保存されます
• データベースには、チャットとメッセージのテーブルが保持されます
• メッセージには、効率的な検索と取得のためのインデックスが付けられます

使用方法

接続すると、Claude の AI 機能を活用して、Claude を通じて WhatsApp の連絡先とやり取りできます。

MCP ツール

Claude は、WhatsApp とやり取りするために以下のツールを利用できます。

• search_contacts：名前または電話番号で連絡先を検索します
• list_messages：オプションのフィルターとコンテキストを指定してメッセージを取得します
• list_chats：メタデータとともに利用可能なチャットを一覧表示します
• get_chat：特定のチャットに関する情報を取得します
• get_direct_chat_by_contact：特定の連絡先とのダイレクトチャットを検索します
• get_contact_chats：特定の連絡先が関わるすべてのチャットを一覧表示します
• get_last_interaction：連絡先との最新のメッセージを取得します
• get_message_context：特定のメッセージの前後のコンテキストを取得します
• send_message：指定した電話番号またはグループ JID に WhatsApp メッセージを送信します
• send_file：指定した宛先にファイル（画像、動画、生音声、ドキュメント）を送信します
• send_audio_message：音声ファイルを WhatsApp のボイスメッセージとして送信します（ファイルが .ogg opus ファイルであるか、ffmpeg がインストールされている必要があります）
• download_media：WhatsApp メッセージからメディアをダウンロードし、ローカルファイルパスを取得します

メディア処理機能

MCP サーバーは、さまざまな種類のメディアの送信と受信の両方に対応しています。

メディアの送信

さまざまな種類のメディアを WhatsApp の連絡先に送信できます。

• 画像、動画、ドキュメント：send_file ツールを使って、サポートされている任意の種類のメディアを共有します。
• ボイスメッセージ：send_audio_message ツールを使って、再生可能な WhatsApp のボイスメッセージとして音声ファイルを送信します。
  • 互換性を最大限に高めるには、音声ファイルを .ogg Opus 形式にしてください。
  • FFmpeg がインストールされている場合、システムは他の音声形式（MP3、WAV など）を必要な形式に自動変換します。
  • FFmpeg がインストールされていなくても、send_file ツールを使って生音声ファイルを送信できますが、再生可能なボイスメッセージとしては表示されません。

メディアのダウンロード

デフォルトでは、メディアのメタデータのみがローカルデータベースに保存されます。メッセージにはメディアが送信されたことが示されます。このメディアにアクセスするには、message_id と chat_jid（メディアを含むメッセージを表示したときに示されます）を指定して、download_media ツールを使用する必要があります。このツールはメディアをダウンロードし、その後、開いたり別のツールに渡したりできるファイルパスを返します。

技術的な詳細

1. Claude が Python MCP サーバーにリクエストを送信します
2. MCP サーバーが Go ブリッジに WhatsApp データを問い合わせるか、SQLite データベースに直接問い合わせます
3. Go が WhatsApp API にアクセスし、SQLite データベースを最新の状態に保ちます
4. データは一連の処理を経て Claude に返されます
5. メッセージを送信する際、リクエストは Claude から MCP サーバー、Go ブリッジを経て WhatsApp に送られます

トラブルシューティング

• uv の実行時に権限の問題が発生した場合は、uv を PATH に追加するか、実行ファイルのフルパスを使用する必要がある場合があります。
• 正しく連携するには、Go アプリケーションと Python サーバーの両方が実行されていることを確認してください。

認証に関する問題

• QR コードが表示されない：QR コードが表示されない場合は、認証スクリプトを再起動してみてください。問題が解決しない場合は、ターミナルが QR コードの表示に対応しているか確認してください。
• WhatsApp にすでにログインしている：セッションがすでに有効な場合、Go ブリッジは QR コードを表示せずに自動的に再接続します。
• デバイスの上限に達した：WhatsApp では、リンクできるデバイスの数に上限があります。この上限に達した場合は、スマートフォンの WhatsApp で既存のデバイスを削除する必要があります（設定 > リンク済みデバイス）。
• メッセージが読み込まれない：初回認証後、メッセージ履歴の読み込みには数分かかることがあります。チャットが多い場合は、特に時間がかかります。
• WhatsApp の同期がずれている：WhatsApp のメッセージとブリッジの同期がずれた場合は、2 つのデータベースファイル（whatsapp-bridge/store/messages.db と whatsapp-bridge/store/whatsapp.db）を両方削除し、ブリッジを再起動して再認証してください。

Claude Desktop との連携に関するその他のトラブルシューティングについては、MCP ドキュメントを参照してください。ドキュメントには、ログの確認や一般的な問題の解決に役立つヒントが記載されています。