WhatsApp Web MCP Server

非常に重要

Meta（Business）API を使用せずに WhatsApp メッセージを自動化することは、WhatsApp の利用規約に違反します！ この MCP サーバーで行うすべてのことについて、あなたが全責任を負います。あなたのアカウントがフラグ付け/制限される可能性があります。

MCP WhatsApp Web（TypeScript）

WhatsApp Web 向けの Model Context Protocol（MCP）サーバーを TypeScript で実装したものです。このプロジェクトは、オリジナルの whatsapp-mcp リポジトリを TypeScript に移植したものです。

この MCP サーバーでは、次のことができます：

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

機能

• TypeScript 実装：開発者体験とコードの信頼性を高めるために完全に型付けされたコードベース
• 選択可能な WhatsApp バックエンド：デフォルトでは whatsapp-web.js を使用し、ブラウザなしで動作するオプションの Baileys バックエンドも利用可能
• MCP サーバー：AI アシスタントとのシームレスな統合のために Model Context Protocol を実装
• メディアサポート：画像、動画、ドキュメント、音声メッセージを送受信
• 複数のトランスポートオプション：stdio と Streamable HTTP トランスポートをサポート — 単一プロセスから同時に両方を使用することも可能（stdio で起動し MCP_HTTP_PORT を設定すると http://127.0.0.1:<port>/mcp が追加で公開され、--http で HTTP のみで実行することもできます）
• 柔軟な認証：QR コード（MCP 画像ツールとして）、ペアリングコード（request_pairing_code ツール、または WHATSAPP_PAIRING_PHONE_NUMBER により起動時に stderr へ自動出力）、および HTTP クライアント向けのオプションの OAuth フロー（MCP_OAUTH=true）。ブラウザの認証ページに WhatsApp の QR コードが表示されます — WhatsApp のリンクを解除するとトークンが失効するため、クライアントは自動的に再認証します

アーキテクチャ

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

1. TypeScript MCP サーバー：Model Context Protocol を実装し、AI アシスタントが WhatsApp とやり取りするための標準化されたツールを提供します
2. WhatsApp バックエンド：共有サービスインターフェースが web.js/Puppeteer または Baileys/WebSocket を選択し、認証を処理し、メッセージの送受信を管理します
3. ツール実装：連絡先、チャット、メッセージ、メディア、認証のための各種ツールを提供します

前提条件

• Node.js >= 22.0.0（Baileys の SQLite 依存関係には Node 22 または 24 を推奨）
• npm または yarn
• デフォルトの webjs バックエンドの場合：Google Chrome または Microsoft Edge（自動検出。動画/GIF コーデックのサポートに必要。その他の操作は Puppeteer にバンドルされた Chromium を使用可能）
• baileys の場合：ネイティブの better-sqlite3 モジュールを含むオプションの依存関係をインストールしてください。実行時に Chrome、Edge、Chromium は不要です。

FFmpeg は ffmpeg-static npm パッケージを通じて自動的にバンドルされます — 手動でのインストールは不要です。FFMPEG_PATH 環境変数を独自のバイナリに指定することで上書きできます。

インストール

npx

npx mcp-whatsapp-web

手動インストール

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
   

   WHATSAPP_BACKEND でバックエンドを選択したり、ログレベルを調整したり、WhatsApp Web のバージョンを固定したり、自動検出されたブラウザ（BROWSER_EXECUTABLE_PATH）や ffmpeg バイナリ（FFMPEG_PATH）を上書きしたりできます。WHATSAPP_HEADLESS=false は web.js のブラウザウィンドウを表示し、WHATSAPP_SESSION_DIR はその永続プロファイルの場所を変更します。作業ディレクトリをまたいで一貫させるには、絶対パスのセッションディレクトリを使用してください。

バックエンドの選択

WHATSAPP_BACKEND=webjs がデフォルトであり、既存のセッションと MCP ツール名を維持します。これは個人の Chrome プロファイルではなく、専用の永続的な LocalAuth プロファイルを使用します。現在はブラウザのネイティブなユーザーエージェントとグラフィックスのデフォルトを保持し、Puppeteer の自動化バナーフラグを省略し、ブラウザサンドボックスを有効のままにします。サンドボックスを無効化する必要があるコンテナでは、明示的に WHATSAPP_NO_SANDBOX=true を設定できます。これらの設定は、自動化が検出されないことを保証するものではありません。

オプションの Baileys バックエンドを使用するには、MCP クライアントの設定または .env で以下の変数を設定し、サーバーを再起動してください:

WHATSAPP_BACKEND=baileys
BAILEYS_SESSION_DIR=C:/path/to/your/baileys-sessions

BAILEYS_SESSION_DIR のデフォルトは <working directory>/baileys-sessions です。上記の例はご自身の絶対ディレクトリに置き換えてください。このバックエンドは get_qr_code または request_pairing_code を使用して別途ペアリングしてください。既存の WHATSAPP_PAIRING_PHONE_NUMBER オプションも機能します。Baileys は web.js のブラウザプロファイルを再利用できません。webjs に戻して、その既存のセッションを再開できます。

Baileys と SQLite は、通常の npm install でインストールされる固定されたオプションの依存関係です。パッケージマネージャーがこれらを省略した場合は、npm install --include=optional を実行してください。SQLite はネイティブアドオンを使用します。サポートされたビルド済みバイナリ、またはローカルのネイティブビルドツールチェーンが必要です。Baileys のインストール時、または既存のシステムブラウザを使用する際に Chromium のダウンロードを避けるには、以下を使用してください:

$env:PUPPETEER_SKIP_DOWNLOAD = 'true'
npm install --include=optional
npm run build

macOS/Linux では、同等のインストールコマンドは PUPPETEER_SKIP_DOWNLOAD=true npm install --include=optional です。Baileys を選択すると、そのドライバーのみが読み込まれ、ブラウザプロセスの起動やクリーンアップは一切行われません。利用できないバックエンドはエラーを発生させます。ドライバーを暗黙的に切り替えたり、別のバックエンドを介して送信を再試行したりすることはありません。

Baileys のセッションと履歴

• 認証情報、Signal キー、連絡先、チャット、メッセージは BAILEYS_SESSION_DIR/session.sqlite に永続化されます。ディレクトリ全体を非公開にし、バージョン管理から除外してください。1 つのセッションディレクトリを所有できるのは、実行中のサーバー 1 つだけです。独立したアカウントには別々のディレクトリを使用してください。
• 通常のシャットダウンではセッションが保持されます。明示的なログアウトまたは無効な認証は、Baileys の認証情報とキャッシュされたアカウントデータを消去し、その OAuth アクセストークンを取り消します。Baileys の HTTP OAuth 状態は、web.js とは別に BAILEYS_SESSION_DIR/oauth-store.json に保存されます。
• get_backend_status は、アクティブなバックエンド、認証、保存されたレコード数、履歴の同期状態を報告します。接続されていることは、履歴の受信が完了したことを意味しません。available の履歴状態は、ローカルデータが利用可能であることを意味し、WhatsApp が完全なアーカイブを提供したことを意味するものではありません。
• 連絡先および履歴ツールは、ローカルの同期済みストアをクエリします。初回の完全な履歴同期はリクエストされ、大規模なアカウントでは時間がかかることがあります。list_messages は、既知のチャットで要求された件数より少ない場合、最大 100 件の古いメッセージを追加でリクエストすることがあり、待機時間には上限があり、チャットごとにクールダウンがあります。遅れて到着した履歴バッチは、その後のクエリのために永続化されます。WhatsApp は依然としてアカウントの履歴の一部しか提供しない可能性があります。
• 返されたメッセージ ID は不透明なものとして扱い、アクティブなバックエンドの ID を使用してください。従来の @c.us 電話番号入力、@s.whatsapp.net、グループ、@lid 識別子がサポートされています。既知の LID/電話番号のマッピングは永続化されます。web.js のメッセージ ID を Baileys に渡すことはできず、その逆も同様です。
• テキスト、メディア、ダウンロード、ボイスノート、および既存の認証ツールは、同じ MCP インターフェースを使用します。ボイスノートの入力はローカルファイルまたは base64 である必要があります。送信前に FFmpeg がそれらをモノラルの Opus/Ogg に変換します。変換が失敗した場合、ツールは別のメッセージタイプを送信することなくエラーを報告します。

Baileys バックエンドはオプトインであり、7.0.0-rc14 に固定されています。アップグレードする前に、特に認証とメッセージ形式の移行について、上流の変更を確認してください。Baileys のドキュメントおよびリリース履歴を参照してください。

FLUJO でのインストール

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

1. FLUJO の MCP セクションに移動します
2. 「Add Server」をクリックします
3. この GitHub リポジトリの URL をコピーして貼り付けます: https://github.com/mario-andreschak/mcp-whatsapp-web
4. 「Parse」、「Clone」、「Install」、「Build」、「Update Server」をクリックします

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

使用方法

MCP サーバーの起動

npm start

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

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

開発モード

npm run dev

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

MCP Inspector でのデバッグ

npm run debug

これにより MCP Inspector ツールが起動します。これは、MCP サーバーをテストおよびデバッグするための Web インターフェースを提供します。Inspector では、次のことができます。

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

Claude Desktop への接続

1. Claude Desktop の構成ファイルを作成します:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "npx",
         "args": [
           "mcp-whatsapp-web"
         ]
       }
     }
   }
   

   PATH_TO をリポジトリへの絶対パスに置き換えます。

2. これを Claude Desktop の構成ディレクトリに 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

3. Claude Desktop を再起動します

Cursor への接続

1. Cursor の構成ファイルを作成します:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "node",
         "args": [
           "PATH_TO/dist/index.js"
         ]
       }
     }
   }
   

   PATH_TO をリポジトリへの絶対パスに置き換えます。

2. これを Cursor の構成ディレクトリに mcp.json として保存します:

   • macOS/Linux: ~/.cursor/mcp.json
   • Windows: %USERPROFILE%\.cursor\mcp.json

3. Cursor を再起動します

認証

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

1. MCP サーバーを起動します
2. 重要: QR コードを生成するには、get_qr_code ツールを使用する必要があります
   • Claude またはその他の AI アシスタントで、「use the get_qr_code tool to authenticate 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 サーバーは、WhatsApp Web への接続のために Puppeteer を使用して Chrome ブラウザを制御します。このサーバーには、孤立した Chrome プロセスを防ぐための堅牢なブラウザプロセス管理システムが含まれています。

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

サーバーは自動的に以下を行います：

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

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

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

npm run cleanup-browsers

このユーティリティは以下を行います：

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 ブラウザプロセスを検出してクリーンアップします
• npm test - ユニットテストスイートを実行します（高速、ブラウザ不要）
• npm run test:watch - 開発中にウォッチモードでユニットテストを実行します
• npm run test:e2e - ビルドしてからエンドツーエンドテストを実行します（ヘッドレスブラウザを含む実際のサーバーを起動します）

トラブルシューティング

認証の問題

• QR コードが表示されない場合は、サーバーを再起動してみてください
• すでに認証済みの場合、QR コードは表示されません（check_auth_status を使用して確認してください）
• 再認証が必要な場合は、先に logout ツールを使用してから、新しい QR コードをリクエストしてください
• WhatsApp はリンクできるデバイス数に制限を設けています。既存のデバイスを削除する必要がある場合があります
• 「No QR code is currently available」というメッセージが表示されても、すでに認証済みであれば、これは通常の動作です - check_auth_status を使用して認証状態を確認してください

接続の問題

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

ブラウザプロセスの問題

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

ライセンス

MIT

---

このプロジェクトは、lharries によるオリジナルの whatsapp-mcp を TypeScript に移植したものです。