WhatsApp MCP サーバー (TypeScript/Baileys)

これは、TypeScript で構築され、 @whiskeysockets/baileysライブラリを使用した WhatsApp 用の Model Context Protocol (MCP) サーバーです。

これにより、個人の WhatsApp アカウントを AI エージェント (デスクトップ アプリまたは Cursor 経由の Anthropic Claude など) に接続して、次のことが可能になります。

• 個人の WhatsApp メッセージを検索します。
• 連絡先を検索します（グループではなく個人）。
• 最近のチャットを一覧表示します。
• 特定のチャットのメッセージ履歴を取得します。
• 個人またはグループにメッセージを送信します。

WhatsApp WebマルチデバイスAPIを使用して、個人のWhatsAppアカウントに直接接続します。すべてのメッセージと認証情報は、SQLiteデータベース（ ./data/ ）と認証キャッシュ（ ./auth_info/ ）にローカルに保存されます。接続されたAIエージェントにデータが送信されるのは、エージェントがMCPツール（エージェントのインターフェースから制御）を明示的に使用した場合のみです。

（オプション：ここに参照例に類似したスクリーンショットまたは GIF を追加することを検討してください）

例

ユーザー: WhatsAppで「Meu amor」に「Te amo」というメッセージを送信します

**アシスタント：**わかりました。まずは連絡先を検索する必要があります。使用ツール： whatsapp.search_contacts

ツールの結果:

**アシスタント：**連絡先が見つかりました。メッセージを送信しています。使用ツール： whatsapp.send_message

ツールの結果:

主な機能（MCPツール）

サーバーは、接続された AI エージェントに次のツールを公開します。

• search_contacts : 名前または電話番号部分 (JID) で連絡先を検索します。
• list_messages : ページ区切りを付けて、特定のチャットのメッセージ履歴を取得します。
• list_chats : チャットを一覧表示します。アクティビティまたは名前で並べ替え可能で、フィルタリング可能、ページ区切りで、オプションで最後のメッセージの詳細が含まれます。
• get_chat : 特定のチャットの詳細情報を取得します。
• get_message_context : コンテキストの特定のメッセージ ID の直前と直後に送信されたメッセージを取得します。
• send_message : 指定された受信者 JID (ユーザーまたはグループ) にテキスト メッセージを送信します。

インストール

前提条件

• **Node.js:**バージョン 23.10.0 以上（ package.jsonに指定）。バージョンはnode -vで確認できます。（TypeScript と SQLite の初期サポートが組み込まれています）
• npm (または yarn/pnpm): 通常は Node.js に付属しています。
• AI クライアント: Anthropic Claude デスクトップ アプリ、Cursor、Cline、Roo Code (または他の MCP 互換クライアント)。

手順

1. このリポジトリをクローンします:
   git clone <your-repo-url> whatsapp-mcp-ts cd whatsapp-mcp-ts
2. 依存関係をインストールします:
   npm install # or yarn install / pnpm install
3. サーバーを初めて実行します。node node使用してメイン スクリプトを直接実行します。
   node src/main.ts
   • 初めて実行すると、 quickchart.ioを使用して QR コード リンクが生成され、デフォルトのブラウザーで開こうとします。
   • WhatsApp モバイル アプリ (設定 > リンクされたデバイス > デバイスのリンク) を使用してこの QR コードをスキャンします。
   • 認証資格情報はauth_info/ディレクトリにローカルに保存されます (これは git では無視されます)。
   • メッセージの同期が開始され、 ./data/whatsapp.db whatsapp.db に保存されます。履歴のサイズによっては時間がかかる場合があります。進捗状況はwa-logs.txtとコンソール出力でご確認ください。
   • このターミナルウィンドウは実行したままにしておいてください。同期が完了したら閉じてください。

AIクライアントの構成

AI クライアントにこの MCP サーバーを起動する方法を伝える必要があります。

1. 設定JSONを準備します。以下のJSON構造をコピーします。 {{PATH_TO_REPO}}このリポジトリをクローンしたディレクトリへの絶対パスに置き換える必要があります。
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "{{PATH_TO_REPO}}/src/main.ts" ], "timeout": 15, // Optional: Adjust startup timeout if needed "disabled": false } } }
   • **絶対パスを取得するには、**ターミナルでwhatsapp-mcp-tsディレクトリに移動し、 pwdを実行します。この出力を{{PATH_TO_REPO}}として使用します。
2. 設定ファイルを保存します。
   • Claude Desktop の場合: JSON をclaude_desktop_config.jsonとして構成ディレクトリに保存します。
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json (おそらくパスですが、必要に応じて確認してください)
     • Linux: ~/.config/Claude/claude_desktop_config.json (おそらくパス。必要に応じて確認してください)
   • カーソルの場合: JSON をmcp.jsonとして構成ディレクトリに保存します。
     • ~/.cursor/mcp.json
3. Claude Desktop / Cursorを再起動します。AIクライアントを閉じて再度開きます。これで「whatsapp」MCPサーバーが検出され、ツールが使用できるようになります。

使用法

サーバーが起動し（ node src/main.ts経由で手動で起動するか、AIクライアントの設定ファイル経由で起動するかは任意）、AIクライアントに接続されたら、エージェントのチャットインターフェースを介してWhatsAppデータを操作できます。連絡先の検索、最近のチャットの一覧表示、メッセージの閲覧、メッセージの送信などが可能です。

アーキテクチャの概要

このアプリケーションは、次の機能を備えた単一の Node.js プロセスです。

1. @whiskeysockets/baileysを使用して WhatsApp Web API に接続し、認証とリアルタイム イベントを処理します。
2. node:sqliteを使用して、WhatsApp のチャットとメッセージを SQLite データベース ( ./data/whatsapp.db ) にローカルに保存します。
3. 標準入出力 (stdio) を介して AI クライアントからの要求をリッスンする@modelcontextprotocol/sdkを使用して MCP サーバーを実行します。
4. ローカル SQLite データベースを照会したり、Baileys ソケットを使用してメッセージを送信したりする MCP ツールを提供します。
5. アクティビティのログ記録にはpinoを使用します (WhatsApp イベントの場合はwa-logs.txt 、MCP サーバー アクティビティの場合はmcp-logs.txt )。

データストレージとプライバシー

• 認証: WhatsApp 接続資格情報は./auth_info/ auth_info/ ディレクトリにローカルに保存されます。
• **メッセージとチャット:**メッセージ履歴とチャットのメタデータは./data/whatsapp.db whatsapp.db SQLite ファイルにローカルに保存されます。
• ローカルデータ: auth_info/とdata/は、誤ってコミットされないように.gitignoreに含まれています。これらのディレクトリは機密情報として扱ってください。
• LLMとの連携： AIエージェントがMCPツール（例： list_messages 、 send_message ）のいずれかをアクティブに使用した場合にのみ、接続された大規模言語モデル（LLM）にデータが送信されます。サーバー自体がデータを他の場所に積極的に送信することはありません。

技術的な詳細

• 言語: TypeScript
• ランタイム: Node.js (>= v23.10.0)
• WhatsApp API: @whiskeysockets/baileys
• MCP SDK: @modelcontextprotocol/sdk
• データベース: node:sqlite (バンドルされた SQLite)
• ログ記録: pino
• スキーマ検証: zod (MCP ツール入力用)

トラブルシューティング

• QR コードの問題:
  • QR コード リンクが自動的に開かない場合は、コンソール出力でquickchart.io URL を確認し、手動で開きます。
  • 携帯電話の WhatsApp アプリで QR コードをすぐにスキャンしてください。
• 認証失敗/ログアウト:
  • 接続がDisconnectReason.loggedOutエラーで切断された場合は、再認証が必要です。サーバーを停止し、 ./auth_info/ディレクトリを削除してサーバーを再起動し（ node src/main.ts ）、新しい QR コードを取得してください。
• メッセージ同期の問題:
  • 初期同期には時間がかかる場合があります。wa wa-logs.txtでアクティビティを確認してください。
  • メッセージが同期されていない、または欠落しているように見える場合は、完全なリセットが必要になる可能性があります。サーバーを停止し、 ./auth_info/と./data/の両方のディレクトリを削除してから、サーバーを再起動して再認証を行い、履歴を再同期してください。
• MCP 接続の問題 (Claude/Cursor):
  • claude_desktop_config.jsonまたはmcp.json内のcommandとargs （特に{{PATH_TO_REPO}} ）を再確認してください。パスが絶対パスで正しいことを確認してください。
  • Node.js が正しくインストールされ、システムの PATH にあることを確認します。
  • AI クライアントのログで、MCP サーバーの起動に関連するエラーを確認します。
  • MCP 関連のエラーについては、このサーバーのログ ( mcp-logs.txt ) を確認してください。
• メッセージ送信エラー:
  • 受信者の JID が正しいことを確認します (例: ユーザーの場合はnumber@s.whatsapp.net 、グループの場合はgroupid@g.us )。
  • Baileys からの具体的なエラーについてはwa-logs.txt確認してください。
• **一般的な問題:**詳細なエラー メッセージについては、 wa-logs.txtとmcp-logs.txtの両方を確認してください。

MCP 統合に関するさらなる問題については、 公式の MCP ドキュメントを参照してください。

クレジット

• https://github.com/lharries/whatsapp-mcpこのコードベースと同じことを行いますが、go と python を使用します。

ライセンス

このプロジェクトは ISC ライセンスの下でライセンスされています ( package.jsonを参照)。