WhatsAppウェブMCP

モデルコンテキストプロトコル（MCP）を介してWhatsApp WebとAIモデルを接続するNode.jsアプリケーション。このプロジェクトは、WhatsAppとのプログラム的なインタラクションのための標準化されたインターフェースを提供し、AI駆動型ワークフローを通じて自動メッセージング、連絡先管理、グループチャット機能を実現します。

概要

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

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

免責事項

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

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

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

学習リソース

WhatsApp Web MCP を実際のシナリオで使用する方法について詳しくは、次の記事を参照してください。

インストール

リポジトリをクローンします。
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コードのスキャンが必要
テストと開発に適しています

Webhookの設定

認証データディレクトリ ( --auth-data-pathで指定) にwebhook.jsonファイルを作成することにより、着信 WhatsApp メッセージを受信するように webhook を構成できます。

Webhook JSON形式

{
  "url": "https://your-webhook-endpoint.com/incoming",
  "authToken": "your-optional-authentication-token",
  "filters": {
    "allowedNumbers": ["+1234567890", "+0987654321"],
    "allowPrivate": true,
    "allowGroups": false
  }
}

設定オプション

オプション	タイプ	説明
`url`	弦	メッセージデータが送信されるWebhookエンドポイントURL
`authToken`	文字列（オプション）	Authorization ヘッダーに Bearer トークンとして含められる認証トークン
`filters.allowedNumbers`	配列（オプション）	メッセージを受信する電話番号のリスト。指定すると、これらの番号からのメッセージのみがWebhookをトリガーします。
`filters.allowPrivate`	ブール値（オプション）	Webhookにプライベートメッセージを送信するかどうか。デフォルト: `true`
`filters.allowGroups`	ブール値（オプション）	グループメッセージをWebhookに送信するかどうか。デフォルト: `true`

Webhookペイロード

メッセージが受信され、フィルターを通過すると、次の JSON ペイロードを含む POST リクエストが構成された URL に送信されます。

{
  "from": "+1234567890",
  "name": "Contact Name",
  "message": "Hello, world!",
  "isGroup": false,
  "timestamp": 1621234567890,
  "messageId": "ABCDEF1234567890"
}

使用法

実行モード

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
`download_media_from_message`	メッセージからメディアをダウンロードする	`messageId` : ダウンロードするメディアを含むメッセージのID
`send_media_message`	WhatsAppの連絡先にメディアメッセージを送信する	`number` : 送信先の電話番号`source` : URIスキームを使用したメディアソース（URLの場合は`http://`または`https://` 、ローカルファイルの場合は`file://`使用） `caption` （オプション）: メディアのテキストキャプション

利用可能なリソース

リソース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/send/media`	役職	メディアメッセージを送信する	`number` : 受信者`source` : URIスキームを使用したメディアソース（URLの場合は`http://`または`https://` 、ローカルファイルの場合は`file://`使用） `caption` （オプション）: テキストキャプション
`/api/messages/{messageId}/media/download`	役職	メッセージからメディアをダウンロードする	なし

グループマネジメント

終点	方法	説明	パラメータ
`/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 のベストプラクティスを適用し、プロジェクト全体で一貫したコードスタイルを維持します。

出版

このプロジェクトでは、npmへの自動公開にGitHub Actionsを使用しています。ワークフローは以下の処理を行います。

バージョンの増分（ patch 、 minor 、 major ）
'v' で始まるバージョンの Git タグ付け (例: v0.2.1)
GitHub Secretsを使ってnpmに公開する

新しいバージョンをリリースするには:

GitHubリポジトリのアクションタブに移動します
「パッケージを公開」ワークフローを選択する
「ワークフローを実行」をクリックします
バージョン増分タイプ（パッチ、マイナー、メジャー）を選択します
「ワークフローを実行」をクリックして公開プロセスを開始します

このワークフローでは、GitHub リポジトリに NPM_TOKEN シークレットを設定する必要があります。

トラブルシューティング

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

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

特徴

メッセージの送受信
メディアメッセージの送信（画像のみ）
メッセージからメディアをダウンロードする（画像、音声、ドキュメント）
グループチャット管理
連絡先の管理と検索
メッセージ履歴の取得

今後の機能

すべてのメディアファイルタイプ（ビデオ、オーディオ、ドキュメント）の送信をサポート
一般的なシナリオ向けの強化されたメッセージテンプレート
高度なグループ管理機能
連絡先の管理（連絡先の追加/削除）
強化されたエラー処理と回復

貢献

リポジトリをフォークする
機能ブランチを作成する
変更をコミットする
ブランチにプッシュする
プルリクエストを作成する

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 を使用して実行している場合) では、ロガーはテスト環境に適した動作を自動的に調整します。

Integrations