WhatsApp MCP Server (TypeScript/Baileys)

WhatsApp MCP サーバー（TypeScript/Baileys）

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

個人の WhatsApp アカウントを AI エージェント（デスクトップアプリ経由の Anthropic Claude や Cursor など）に接続することで、次のことが可能になります。

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

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

（任意：参考例のようなスクリーンショットまたは GIF を追加することを検討してください）

例

ユーザー： WhatsApp で「Meu amor」に「Te amo」とメッセージを送信してください

---

アシスタント： まず連絡先を見つける必要があります。 ツールを使用中：whatsapp.search_contacts

{
  "query": "Meu amor"
}

---

ツールの結果：

[
  {
    "jid": "[email protected]",
    "name": "Meu Amor"
  }
]

---

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

{
  "recipient": "[email protected]",
  "message": "Te amo"
}

---

ツールの結果：

Message sent successfully to [email protected] (ID: XXXXXXXXXXX).

主な機能（MCP ツール）

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

• search_contacts：名前または電話番号の一部（JID）で連絡先を検索します。
• list_messages：ページネーションを使用して、特定のチャットのメッセージ履歴を取得します。
• list_chats：チャットを一覧表示します。アクティビティまたは名前で並べ替えたり、フィルターを適用したり、ページネーションを使用したりできます。また、最後のメッセージの詳細を任意で含めることもできます。
• get_chat：特定のチャットに関する詳細情報を取得します。
• get_message_context：コンテキストを把握するため、特定のメッセージ ID の直前と直後に送信されたメッセージを取得します。
• send_message：指定した宛先 JID（ユーザーまたはグループ）にテキストメッセージを送信します。

インストール

Smithery 経由でインストールする

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

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

前提条件

• Node.js： バージョン 23.10.0 以降（package.json で指定）。node -v でバージョンを確認できます。（TypeScript と SQLite の初期サポートが組み込まれています）
• npm（または yarn/pnpm）：通常は Node.js に同梱されています。
• AI クライアント： Anthropic Claude Desktop アプリ、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 src/main.ts
   

   • 初回実行時には、quickchart.io を使って QR コードのリンクが生成され、デフォルトのブラウザーで開こうとします。
   • WhatsApp モバイルアプリでこの QR コードをスキャンします（設定 > リンク済みデバイス > デバイスをリンク）。
   • 認証情報は auth_info/ ディレクトリにローカル保存されます（このディレクトリは git の対象外です）。
   • メッセージの同期が始まり、./data/whatsapp.db に保存されます。履歴の量によっては、完了までに時間がかかる場合があります。進行状況は wa-logs.txt とコンソール出力で確認してください。
   • このターミナルウィンドウは開いたままにしてください。同期後は閉じてもかまいません。

AI クライアントの設定

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

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（一般的なパスです。必要に応じて確認してください）
   • Cursor の場合： 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. @modelcontextprotocol/sdk を使用して MCP サーバーを実行し、標準入出力（stdio）を介して AI クライアントからのリクエストを待ち受けます。
4. ローカルの SQLite データベースにクエリを実行する、または Baileys ソケットを使ってメッセージを送信する MCP ツールを提供します。
5. pino を使用してアクティビティを記録します（WhatsApp のイベントは wa-logs.txt、MCP サーバーのアクティビティは mcp-logs.txt に記録されます）。

データの保存とプライバシー

• 認証： WhatsApp の接続認証情報は ./auth_info/ ディレクトリにローカル保存されます。
• メッセージとチャット： メッセージ履歴とチャットのメタデータは、SQLite ファイル ./data/whatsapp.db にローカル保存されます。
• ローカルデータ： 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-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-logs.txt）で、MCP 関連のエラーがないか確認してください。
• メッセージ送信エラー：
  • 宛先の JID が正しいことを確認してください（ユーザーの場合は [email protected]、グループの場合は [email protected] など）。
  • wa-logs.txt で、Baileys による具体的なエラーを確認してください。
• 一般的な問題： 詳細なエラーメッセージについては、wa-logs.txt と mcp-logs.txt の両方を確認してください。

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

クレジット

• https://github.com/lharries/whatsapp-mcp このコードベースと同じことを Go と Python で実現します。

ライセンス

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