WhatsAppウェブMCP

モデルコンテキストプロトコル（MCP）を用いた、WhatsApp WebとAIモデル間の強力なブリッジ。このプロジェクトにより、ClaudeのようなAIモデルが標準化されたインターフェースを介してWhatsAppとやり取りできるようになり、プログラムによるWhatsAppのやり取りの自動化と強化が容易になります。

概要

WhatsApp Web MCP は、次の方法で WhatsApp Web と AI モデル間のシームレスな統合を実現します。

• モデルコンテキストプロトコル（MCP）による標準化されたインターフェースの作成

• WhatsApp機能へのMCPサーバーアクセスを提供

• SSEまたはコマンドモードによる柔軟な展開オプションの提供

• WhatsAppクライアントの直接統合とAPIベースの接続の両方をサポート

免責事項

重要: このツールはテスト目的のみであり、実稼働環境では使用しないでください。

WhatsApp Webプロジェクトからの免責事項:

このプロジェクトは、WhatsAppまたはその子会社、関連会社とは一切関係がなく、提携、承認、推奨、または公式な関係もありません。WhatsAppの公式ウェブサイトはwhatsapp.comです。「WhatsApp」および関連する名称、マーク、エンブレム、画像は、それぞれの所有者の登録商標です。また、この方法を使用してもブロックされないという保証はありません。WhatsAppはプラットフォーム上でボットや非公式クライアントを許可していないため、完全に安全であるとは考えられません。

インストール

1. リポジトリをクローンします。

   git clone https://github.com/pnizer/wweb-mcp.git cd wweb-mcp

2. グローバルにインストールするか、npx と一緒に使用します。

   # Install globally npm install -g . # Or use with npx directly npx .

3. Docker でビルド:

   docker build . -t wweb-mcp:latest

構成

コマンドラインオプション

APIキー認証

APIモードで実行する場合、WhatsApp APIサーバーはAPIキーを使用した認証を必要とします。APIキーはWhatsApp APIサーバーの起動時に自動的に生成され、ログに表示されます。

MCP サーバーを WhatsApp API サーバーに接続するには、 --api-keyまたは-kオプションを使用してこの API キーを提供する必要があります。

API キーは認証データ ディレクトリ ( --auth-data-pathで指定) に保存され、WhatsApp API サーバーの再起動後も保持されます。

認証方法

ローカル認証（推奨）

• QRコードを1回スキャンする

• 資格情報はセッション間で保持されます

• 長期運用でも安定

認証なし

• デフォルトの方法

• 起動ごとにQRコードのスキャンが必要

• テストと開発に適しています

使用法

実行モード

WhatsApp API サーバー

REST エンドポイントを通じて WhatsApp 機能を公開するスタンドアロン WhatsApp API サーバーを実行します。

MCP サーバー (スタンドアロン)

WhatsApp Web に直接接続する MCP サーバーを実行します。

MCP サーバー (API クライアント)

WhatsApp API サーバーに接続する MCP サーバーを実行します。

利用可能なツール

利用可能なリソース

REST APIエンドポイント

連絡先とメッセージ

グループマネジメント

AI統合

クロードデスクトップ統合

オプション1: NPXを使用する

1. WhatsApp API サーバーを起動します。

   npx wweb-mcp -m whatsapp-api -s local

2. WhatsAppモバイルアプリでQRコードをスキャンします

3. ログに表示される API キーをメモします。

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

4. Claude Desktop 構成に以下を追加します。

   { "mcpServers": { "whatsapp": { "command": "npx", "args": [ "wweb-mcp", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://localhost:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

オプション2: Dockerを使用する

1. Docker で WhatsApp API サーバーを起動します。

   docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth

2. WhatsAppモバイルアプリでQRコードをスキャンします

3. ログに表示される API キーをメモします。

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

4. Claude Desktop 構成に以下を追加します。

   { "mcpServers": { "whatsapp": { "command": "docker", "args": [ "run", "-i", "--rm", "wweb-mcp:latest", "-m", "mcp", "-s", "local", "-c", "api", "-t", "command", "--api-base-url", "http://host.docker.internal:3001/api", "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" ] } } }

5. Claudeデスクトップを再起動します

6. WhatsApp機能はClaudeのインターフェースを通じて利用可能になります

建築

このプロジェクトは、明確な関心の分離に基づいて構成されています。

コンポーネント

1. WhatsAppService : WhatsAppとやりとりするためのコアビジネスロジック

2. WhatsAppApiClient : WhatsApp APIに接続するためのクライアント

3. API ルーター: REST API の Express ルート

4. MCP サーバー: モデルコンテキストプロトコルの実装

展開オプション

1. WhatsApp API サーバー: スタンドアロン REST API サーバー

2. MCPサーバー（スタンドアロン） ：WhatsApp Webへの直接接続

3. MCP サーバー (API クライアント) : WhatsApp API サーバーへの接続

このアーキテクチャにより、次のような柔軟な展開シナリオが可能になります。

• APIサーバーとMCPサーバーを異なるマシンで実行する

• MCP サーバーを既存の API サーバーのクライアントとして使用する

• シンプルさのためにすべてを1台のマシンで実行する

発達

プロジェクト構造

ソースから構築

テスト

このプロジェクトではユニットテストにJestを使用しています。テストを実行するには、以下の手順に従ってください。

リンティングとフォーマット

このプロジェクトでは、コードの品質とフォーマットのために ESLint と Prettier を使用しています。

リンティング構成は TypeScript のベスト プラクティスを適用し、プロジェクト全体で一貫したコード スタイルを維持します。

トラブルシューティング

クロードデスクトップ統合の問題

• Claudeではwweb-mcpをコマンドスタンドアロンモードで起動できません。これは、Claudeが複数のプロセスを複数回起動し、各wweb-mcpが同じWhatsApp認証を共有できないPuppeteerセッションを開く必要があるためです。この制限のため、Claudeとの適切な統合を可能にするため、アプリをMCPモードとAPIモードに分割しました。

今後の機能

• 受信メッセージやその他の WhatsApp イベント用の Webhook を作成する

• メディアファイル（画像、音声、ドキュメント）の送信をサポート

• グループチャット管理機能

• 連絡先の管理（連絡先の追加/削除）

• 一般的なシナリオのメッセージテンプレート

• 強化されたエラー処理と回復

貢献

1. リポジトリをフォークする

2. 機能ブランチを作成する

3. 変更をコミットする

4. ブランチにプッシュする

5. プルリクエストを作成する

PR は次の点に注意してください:

• 既存のコードスタイルに従う

• 適切なテストを含む

• 必要に応じてドキュメントを更新する

• 変更点を詳しく説明します

依存関係

WhatsApp Web.js

このプロジェクトでは、WhatsApp Webブラウザアプリを介して接続するWhatsApp Web用の非公式JavaScriptクライアントライブラリであるwhatsapp-web.jsを使用しています。詳細については、 whatsapp-web.jsのGitHubリポジトリをご覧ください。

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。

ログ記録

WhatsApp Web MCPには、Winstonで構築された堅牢なログシステムが搭載されています。このログシステムは以下を提供します。

• 複数のログ レベル (エラー、警告、情報、http、デバッグ)

• 色分けされたログを含むコンソール出力

• APIエンドポイントのHTTPリクエスト/レスポンスのログ記録

• 構造化されたエラー処理

• 環境に応じたログレベル（開発 vs. 本番）

• MCP コマンド モードで実行している場合、すべてのログは stderr に送信されます。

ログレベル

アプリケーションは、詳細度の順に次のログ レベルをサポートしています。

1. エラー- アプリケーションの機能を妨げる重大なエラー

2. 警告- アプリケーションを停止しないが注意を必要とする警告

3. info - アプリケーションの状態とイベントに関する一般情報

4. http - HTTP リクエスト/レスポンスのログ記録

5. デバッグ- 詳細なデバッグ情報

ログレベルの設定

--log-levelまたは-lフラグを使用して、アプリケーションの起動時にログ レベルを設定できます。

または、グローバルインストールを使用する場合:

コマンドモードログ

MCPコマンドモード（ --mode mcp --transport command ）で実行している場合、すべてのログはstderrに出力されます。これは、stdoutをデータ出力に、stderrをログ出力と診断に使用するコマンドラインツールにとって重要です。これにより、stdoutを介したMCPプロトコル通信がログメッセージによって妨害されることがなくなります。

テスト環境

テスト環境 ( NODE_ENV=testの場合、または Jest を使用して実行している場合) では、ロガーはテスト環境に適した動作を自動的に調整します。