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」というメッセージを送信します

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

ツールの結果:

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

ツールの結果:

Related MCP server: API Tester MCP Server

主な機能（MCPツール）

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

• search_contacts : 名前または電話番号部分 (JID) で連絡先を検索します。

• list_messages : ページ区切りを付けて、特定のチャットのメッセージ履歴を取得します。

• list_chats : チャットを一覧表示します。アクティビティまたは名前で並べ替え可能で、フィルタリング可能、ページ区切りで、オプションで最後のメッセージの詳細が含まれます。

• get_chat : 特定のチャットの詳細情報を取得します。

• get_message_context : コンテキストの特定のメッセージ ID の直前と直後に送信されたメッセージを取得します。

• send_message : 指定された受信者 JID (ユーザーまたはグループ) にテキスト メッセージを送信します。

インストール

Smithery経由でインストール

Smithery経由で Claude Desktop 用の WhatsApp MCP サーバーを自動的にインストールするには:

前提条件

• **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を準備します。に置き換える必要があります。

   { "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を参照)。