WhatsAppウェブMCP

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

概要

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

モデルコンテキストプロトコル（MCP）による標準化されたインターフェースの作成
WhatsApp機能へのMCPサーバーアクセスを提供
SSEまたはコマンドモードによる柔軟な展開オプションの提供
WhatsAppクライアントの直接統合とAPIベースの接続の両方をサポート

Related MCP server: MCP Evolution API

免責事項

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

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

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

インストール

リポジトリをクローンします。
git clone https://github.com/pnizer/wweb-mcp.git cd wweb-mcp
グローバルにインストールするか、npx と一緒に使用します。
# Install globally npm install -g . # Or use with npx directly npx .
Docker でビルド:
docker build . -t wweb-mcp:latest

構成

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

オプション	エイリアス	説明	選択肢	デフォルト
`--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サーバーの起動時に自動的に生成され、ログに表示されます。

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

認証方法

ローカル認証（推奨）

QRコードを1回スキャンする
資格情報はセッション間で保持されます
長期運用でも安定

認証なし

デフォルトの方法
起動ごとにQRコードのスキャンが必要
テストと開発に適しています

使用法

実行モード

WhatsApp API サーバー

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

npx wweb-mcp --mode whatsapp-api --api-port 3001

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

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

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

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

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

# First, start the WhatsApp API server and note the API key from the logs npx wweb-mcp --mode whatsapp-api --api-port 3001 # Then, start the MCP server with the API key npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

利用可能なツール

道具	説明	パラメータ
`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 サーバーを起動します。
npx wweb-mcp -m whatsapp-api -s local
WhatsAppモバイルアプリでQRコードをスキャンします
ログに表示される API キーをメモします。
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
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を使用する

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
WhatsAppモバイルアプリでQRコードをスキャンします
ログに表示される API キーをメモします。
WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
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" ] } } }
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台のマシンで実行する

発達

プロジェクト構造

src/ ├── whatsapp-client.ts # WhatsApp Web client implementation ├── whatsapp-service.ts # Core business logic ├── whatsapp-api-client.ts # Client for the WhatsApp API ├── api.ts # REST API router ├── mcp-server.ts # MCP protocol implementation └── main.ts # Application entry point

ソースから構築

npm run build

テスト

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

# Run all tests npm test # Run tests in watch mode during development npm run test:watch # Generate test coverage report npm run test:coverage

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

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

# Run linter npm run lint # Fix linting issues automatically npm run lint:fix # Format code with Prettier npm run format # Validate code (lint + test) npm run validate

リンティング構成は 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フラグを使用して、アプリケーションの起動時にログレベルを設定できます。

npm start -- --log-level=debug

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

wweb-mcp --log-level=debug

コマンドモードログ

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

テスト環境

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