hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Integrations
Provides a bridge to WhatsApp Web functionality, enabling tools to send/receive messages, search contacts, manage groups, retrieve chat histories, and perform other WhatsApp operations programmatically.
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はプラットフォーム上でボットや非公式クライアントを許可していないため、完全に安全であるとは考えられません。
インストール
- リポジトリをクローンします。Copy
- グローバルにインストールするか、npx と一緒に使用します。Copy
- Docker でビルド:Copy
構成
コマンドラインオプション
| オプション | エイリアス | 説明 | 選択肢 | デフォルト |
|---|---|---|---|---|
--mode | -m | 実行モード | mcp 、 whatsapp-api | mcp |
--mcp-mode | -c | MCP接続モード | standalone 、 api | standalone |
--transport | -t | MCPトランスポートモード | sse 、 command | sse |
--sse-port | -p | SSEサーバーのポート | - | 3002 |
--api-port | - | WhatsApp APIサーバーのポート | - | 3001 |
--auth-data-path | -a | 認証データを保存するパス | - | .wwebjs_auth |
--auth-strategy | -s | 認証戦略 | local 、 none | local |
--api-base-url | -b | API モードを使用する場合の MCP の API ベース URL | - | http://localhost:3001/api |
--api-key | -k | APIモード使用時のWhatsApp Web REST APIのAPIキー | - | '' |
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 サーバーを実行します。
利用可能なツール
| 道具 | 説明 | パラメータ |
|---|---|---|
get_status | WhatsAppクライアントの接続ステータスを確認する | なし |
send_message | WhatsAppの連絡先にメッセージを送信する | number : 送信先の電話番号message : 送信するテキスト内容 |
search_contacts | 名前または番号で連絡先を検索する | query : 連絡先を見つけるための検索語 |
get_messages | 特定のチャットからメッセージを取得する | number : メッセージを取得する電話番号limit (オプション): 取得するメッセージの数 |
get_chats | WhatsAppチャットのリストを取得する | なし |
create_group | 新しいWhatsAppグループを作成する | name : グループ名、 participants : 追加する電話番号の配列 |
add_participants_to_group | 既存のグループに参加者を追加する | groupId : グループのID participants : 追加する電話番号の配列 |
get_group_messages | グループからメッセージを取得する | groupId : グループのID limit (オプション): 取得するメッセージの数 |
send_group_message | グループにメッセージを送信する | groupId : グループのID message : 送信するテキストの内容 |
search_groups | 名前、説明、メンバー名でグループを検索します | query : グループを見つけるための検索語 |
get_group_by_id | 特定のグループに関する詳細情報を取得する | groupId : 取得するグループのID |
利用可能なリソース
| リソースURI | 説明 |
|---|---|
whatsapp://contacts | WhatsAppのすべての連絡先のリスト |
whatsapp://messages/{number} | 特定のチャットからのメッセージ |
whatsapp://chats | WhatsAppチャットのリスト |
whatsapp://groups | すべてのWhatsAppグループのリスト |
whatsapp://groups/search | 名前、説明、メンバー名でグループを検索します |
whatsapp://groups/{groupId}/messages | 特定のグループからのメッセージ |
REST APIエンドポイント
連絡先とメッセージ
| 終点 | 方法 | 説明 | パラメータ |
|---|---|---|---|
/api/status | 得る | WhatsAppの接続ステータスを取得する | なし |
/api/contacts | 得る | すべての連絡先を取得 | なし |
/api/contacts/search | 得る | 連絡先を検索 | query : 検索語 |
/api/chats | 得る | すべてのチャットを取得 | なし |
/api/messages/{number} | 得る | チャットからメッセージを受け取る | limit （クエリ）：メッセージ数 |
/api/send | 役職 | メッセージを送信 | number : 受信者message : メッセージ内容 |
グループマネジメント
| 終点 | 方法 | 説明 | パラメータ |
|---|---|---|---|
/api/groups | 得る | すべてのグループを取得 | なし |
/api/groups/search | 得る | グループを検索 | query : 検索語 |
/api/groups/create | 役職 | 新しいグループを作成する | name : グループ名participants : 数字の配列 |
/api/groups/{groupId} | 得る | 特定のグループに関する詳細情報を取得する | なし |
/api/groups/{groupId}/messages | 得る | グループからメッセージを受け取る | limit （クエリ）：メッセージ数 |
/api/groups/{groupId}/participants/add | 役職 | グループにメンバーを追加する | participants : 数値の配列 |
/api/groups/send | 役職 | グループにメッセージを送信する | groupId : グループID message : メッセージの内容 |
AI統合
クロードデスクトップ統合
オプション1: NPXを使用する
- WhatsApp API サーバーを起動します。Copy
- WhatsAppモバイルアプリでQRコードをスキャンします
- ログに表示される API キーをメモします。Copy
- Claude Desktop 構成に以下を追加します。Copy
オプション2: Dockerを使用する
- Docker で WhatsApp API サーバーを起動します。Copy
- WhatsAppモバイルアプリでQRコードをスキャンします
- ログに表示される API キーをメモします。Copy
- Claude Desktop 構成に以下を追加します。Copy
- Claudeデスクトップを再起動します
- WhatsApp機能はClaudeのインターフェースを通じて利用可能になります
建築
このプロジェクトは、明確な関心の分離に基づいて構成されています。
コンポーネント
- WhatsAppService : WhatsAppとやりとりするためのコアビジネスロジック
- WhatsAppApiClient : WhatsApp APIに接続するためのクライアント
- API ルーター: REST API の Express ルート
- MCP サーバー: モデルコンテキストプロトコルの実装
展開オプション
- WhatsApp API サーバー: スタンドアロン REST API サーバー
- MCPサーバー（スタンドアロン） ：WhatsApp Webへの直接接続
- 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 を作成する
- メディアファイル（画像、音声、ドキュメント）の送信をサポート
- グループチャット管理機能
- 連絡先の管理（連絡先の追加/削除）
- 一般的なシナリオのメッセージテンプレート
- 強化されたエラー処理と回復
貢献
- リポジトリをフォークする
- 機能ブランチを作成する
- 変更をコミットする
- ブランチにプッシュする
- プルリクエストを作成する
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 に送信されます。
ログレベル
アプリケーションは、詳細度の順に次のログ レベルをサポートしています。
- エラー- アプリケーションの機能を妨げる重大なエラー
- 警告- アプリケーションを停止しないが注意を必要とする警告
- info - アプリケーションの状態とイベントに関する一般情報
- http - HTTP リクエスト/レスポンスのログ記録
- デバッグ- 詳細なデバッグ情報
ログレベルの設定
--log-levelまたは-lフラグを使用して、アプリケーションの起動時にログ レベルを設定できます。
または、グローバルインストールを使用する場合:
コマンドモードログ
MCPコマンドモード（ --mode mcp --transport command ）で実行している場合、すべてのログはstderrに出力されます。これは、stdoutをデータ出力に、stderrをログ出力と診断に使用するコマンドラインツールにとって重要です。これにより、stdoutを介したMCPプロトコル通信がログメッセージによって妨害されることがなくなります。
テスト環境
テスト環境 ( NODE_ENV=testの場合、または Jest を使用して実行している場合) では、ロガーはテスト環境に適した動作を自動的に調整します。
This server cannot be installed
モデル コンテキスト プロトコルを使用して WhatsApp Web を AI モデルに接続するブリッジ。これにより、Claude やその他の AI システムが標準化されたインターフェースを通じて WhatsApp と対話できるようになります。