mcp-whatsapp-web

MCP WhatsApp Web（TypeScript）

TypeScriptで実装されたWhatsApp Web用のモデルコンテキストプロトコル（MCP）サーバー。このプロジェクトは、オリジナルのwhatsapp-mcpリポジトリのTypeScriptポートです。

この MCP サーバーを使用すると、次のことが可能になります。

• 個人の WhatsApp メッセージ（メディアを含む）を検索して読む
• 連絡先を検索する
• 個人またはグループにメッセージを送信する
• メディアファイル（画像、動画、ドキュメント、音声）の送受信

特徴

• TypeScript 実装: 開発者エクスペリエンスとコードの信頼性を向上させる、完全に型付けされたコードベース
• WhatsApp Web統合: WhatsApp Webへの直接接続にはwhatsapp-web.jsを使用します
• MCP サーバー: AI アシスタントとのシームレスな統合を実現するモデル コンテキスト プロトコルを実装します。
• メディアサポート: 画像、ビデオ、ドキュメント、音声メッセージの送受信
• 複数のトランスポートオプション:柔軟な統合のためにstdioとSSEトランスポートの両方をサポート

建築

この MCP サーバーは次の要素で構成されています。

1. TypeScript MCP Server : モデルコンテキストプロトコルを実装し、AIアシスタントがWhatsAppと対話するための標準化されたツールを提供します。
2. WhatsApp Webサービス: whatsapp-web.jsを介してWhatsApp Webに接続し、認証を処理し、メッセージの送受信を管理します。
3. ツールの実装: 連絡先、チャット、メッセージ、メディア、認証のためのさまざまなツールを提供します

前提条件

• Node.js >= 18.0.0
• npmまたはyarn
• Chrome/Chromium（Puppeteer が WhatsApp Web 接続に使用）
• FFmpeg（オプション、オーディオメッセージの変換用）

インストール

手動インストール

1. このリポジトリをクローンする
   git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git cd mcp-whatsapp-web
2. 依存関係をインストールする
   npm install
3. プロジェクトを構築する
   npm run build
4. 環境変数を設定する（オプション）サンプル環境ファイルをコピーし、必要に応じて変更します。
   cp .env.example .env
   必要に応じて、ログ レベルを調整し、FFmpeg へのパスを指定できます。

FLUJOを使用したインストール

FLUJO は合理化されたインストール プロセスを提供します。

1. FLUJOのMCPセクションに移動します
2. 「サーバーを追加」をクリックします
3. この GitHub リポジトリの URL をコピーして貼り付けます: https://github.com/mario-andreschak/mcp-whatsapp-web
4. 「解析」、「クローン」、「インストール」、「ビルド」、「サーバーの更新」をクリックします。

FLUJO はクローン作成、依存関係のインストール、ビルドのプロセスを自動的に処理します。

使用法

MCPサーバーの起動

これにより、デフォルトで stdio トランスポートを使用して MCP サーバーが起動します。これは、Claude Desktop または同様のアプリケーションとの統合に適しています。

**重要：**サーバーの初回起動後、 get_qr_codeツールを使用してQRコードをスマートフォンでスキャンし、WhatsAppで認証する必要があります。詳細な手順については、 「認証」セクションをご覧ください。

開発モード

これにより、TypeScript 監視モードと自動サーバー再起動を備えた開発モードでサーバーが起動します。

MCP Inspectorによるデバッグ

MCP Inspectorツールが起動します。このツールは、MCPサーバーのテストとデバッグのためのWebインターフェースを提供します。このツールでは、以下のことが可能です。

• 利用可能なすべてのツールとそのスキーマを表示する
• ツールを直接実行し、その応答を確認する
• AIアシスタントに接続せずにサーバーをテストする
• デバッグツールの実行と応答の検査

Claudeデスクトップに接続しています

1. Claude Desktop の設定ファイルを作成します。
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   PATH_TOリポジトリへの絶対パスに置き換えます。
2. これをclaude_desktop_config.jsonとして Claude Desktop 構成ディレクトリに保存します。
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. Claudeデスクトップを再起動します

カーソルに接続

1. カーソルの設定ファイルを作成します。
   { "mcpServers": { "whatsapp": { "command": "node", "args": [ "PATH_TO/dist/index.js" ] } } }
   PATH_TOリポジトリへの絶対パスに置き換えます。
2. これをカーソル構成ディレクトリにmcp.jsonとして保存します。
   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json
3. カーソルを再開

認証

サーバーを初めて実行するときには、WhatsApp で認証する必要があります。

1. MCPサーバーを起動する
2. 重要: QRコードを生成するにはget_qr_codeツールを使用する必要があります
   • Claude や他の AI アシスタントでは、「get_qr_code ツールを使用して WhatsApp を認証する」ように明示的に要求します。
   • アシスタントはこのツールを呼び出してQRコード画像を表示します
3. WhatsAppモバイルアプリでQRコードをスキャンします
   • 携帯電話でWhatsAppを開きます
   • 「設定」>「リンクされたデバイス」>「デバイスをリンク」に移動します
   • 表示されたQRコードに携帯電話のカメラを向けます

セッションはwhatsapp-sessionsディレクトリにローカルに保存され、次回の実行時に自動的に再利用されます。QRコードで認証しないと、WhatsAppの機能を一切ご利用いただけません。

認証ステータスとログアウト

現在の認証ステータスを確認し、セッションを管理できます。

• check_auth_statusツールを使用して、現在認証されているかどうかを確認します。
• 別の WhatsApp アカウントで認証したり、再認証したりする必要がある場合:
  1. logoutツールを使用して現在のセッションからログアウトします
  2. 次に、 get_qr_codeツールを使用して新しいQRコードで認証します。

これは特に次の場合に役立ちます:

• 異なるWhatsAppアカウントを切り替えたい
• セッションが期限切れまたは無効になりました
• 接続に問題が発生しているため、再認証が必要です

利用可能なMCPツール

認証

• get_qr_code - WhatsApp Web認証用のQRコードを取得する
• check_auth_status - WhatsAppで現在認証されているかどうかを確認します
• logout - WhatsAppからログアウトし、現在のセッションをクリアします

連絡先

• search_contacts - 名前または電話番号で連絡先を検索します
• get_contact - 特定の連絡先に関する情報を取得する

チャット

• list_chats - メタデータを含む利用可能なチャットを一覧表示する
• get_chat - 特定のチャットに関する情報を取得する
• get_direct_chat_by_contact - 特定の連絡先との直接チャットを見つける

メッセージ

• list_messages - オプションのフィルターを使用してメッセージを取得する
• get_message - IDで特定のメッセージを取得する
• send_message - チャットにテキストメッセージを送信する

メディア

• send_file - チャットにファイル（画像、動画、ドキュメント）を送信する
• send_audio_message - 音声メッセージ（音声メモ）を送信する
• download_media - メッセージからメディアをダウンロードする

ブラウザプロセス管理

このMCPサーバーは、Puppeteerを使用してChromeブラウザを制御し、WhatsApp Web接続を実現します。このサーバーには、孤立したChromeプロセスを防ぐための堅牢なブラウザプロセス管理システムが搭載されています。

自動ブラウザクリーンアップ

サーバーは自動的に次の処理を実行します。

• PID追跡システムを使用してChromeブラウザのプロセスを追跡します
• 起動時に孤立したプロセスをクリーンアップします
• シャットダウン時にブラウザのプロセスを適切に閉じます
• .chrome-pids.jsonにブラウザ PID の記録を保持します。

手動ブラウザクリーンアップ

自動的にクリーンアップされなかった孤立した Chrome プロセスに気付いた場合は、付属のクリーンアップ ユーティリティを使用できます。

このユーティリティは次のことを行います。

1. WhatsApp Webに関連する可能性のあるChromeプロセスをスキャンします
2. 孤立している可能性のあるプロセスのリストを表示する
3. 解雇する前に確認を求める
4. PID追跡ファイルをクリーンアップする

発達

プロジェクト構造

• src/index.ts - エントリポイント
• src/server.ts - MCP サーバーの実装
• src/services/whatsapp.ts - WhatsApp Web サービス
• src/tools/ - WhatsAppのさまざまな機能のためのツール実装
• src/types/ - TypeScript 型定義
• src/utils/ - ユーティリティ関数

スクリプト

• npm run build - TypeScriptコードをビルドする
• npm run dev - ウォッチ付きの開発モードで実行
• npm run lint - ESLint を実行する
• npm run format - Prettier でコードをフォーマットする
• npm run cleanup-browsers - 孤立した Chrome ブラウザのプロセスを検出してクリーンアップします

トラブルシューティング

認証の問題

• QRコードが表示されない場合は、サーバーを再起動してください。
• すでに認証されている場合は、QR コードは表示されません ( check_auth_statusを使用して確認してください)
• 再認証が必要な場合は、まずlogoutツールを使用してから、新しいQRコードをリクエストしてください。
• WhatsAppはリンクできるデバイスの数に制限があるため、既存のデバイスを削除する必要がある場合があります。
• 「現在QRコードは使用できません」というメッセージが表示されても、すでに認証されている場合は、これは正常な動作ですcheck_auth_statusを使用して認証ステータスを確認してください。

接続の問題

• 安定したインターネット接続があることを確認してください
• 接続に失敗した場合は、サーバーを再起動してください
• 詳細なエラーメッセージについてはログを確認してください

ブラウザプロセスの問題

• CPU使用率やメモリ消費量が高い場合は、孤立したChromeプロセスが存在する可能性があります。
• npm run cleanup-browsersを実行して孤立したプロセスを検出しクリーンアップします。
• サーバーが頻繁にクラッシュする場合は、孤立したプロセスをチェックしてクリーンアップしてください。
• Windowsでは、タスクマネージャーを使用して、コマンドラインで「headless」を使用して複数のChromeプロセスを探すこともできます。
• Linux/macOSでは、 ps aux | grep chromeを使用して孤立したプロセスを確認します。

ライセンス

マサチューセッツ工科大学

このプロジェクトは、 lharriesによるオリジナルのwhatsapp-mcpの TypeScript ポートです。