WhatsApp Web MCP

WhatsApp Web MCP

WhatsApp WebをModel Context Protocol（MCP）経由でAIモデルに接続するNode.jsアプリケーションです。このプロジェクトは、WhatsAppとプログラムからやり取りするための標準化されたインターフェースを提供し、AI主導のワークフローを通じて、メッセージの自動送信、連絡先の管理、グループチャット機能を実現します。

概要

WhatsApp Web MCPは、以下の方法でWhatsApp WebとAIモデルをシームレスに統合します。

• Model Context Protocol（MCP）を通じて標準化されたインターフェースを作成
• WhatsAppの機能にアクセスするためのMCP サーバーを提供
• SSEモードまたはコマンドモードによる柔軟なデプロイオプションを提供
• WhatsAppクライアントとの直接連携と、APIベースの接続の両方をサポート

免責事項

重要：このツールはテスト目的でのみ使用してください。本番環境では使用しないでください。

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

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

学習リソース

実際のシナリオでWhatsApp Web MCPを使用する方法については、以下の記事をご覧ください。

• AIとWhatsAppの統合：WhatsApp MCP サーバーの設定ガイド
• OpenAI Agents Python SDKとAnthropicのMCPの統合

インストール

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
   

設定

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

オプション	エイリアス	説明	選択肢	デフォルト
--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コードを一度スキャンします
• 認証情報はセッション間で保持されます
• 長期運用でもより安定します

認証なし

• デフォルトの方法です
• 起動のたびに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	String	メッセージデータの送信先となる Webhook エンドポイント URL
authToken	String (optional)	Bearer トークンとして Authorization ヘッダーに含める認証トークン
filters.allowedNumbers	Array (optional)	メッセージを受け付ける電話番号のリスト。指定した場合、これらの番号からのメッセージのみが Webhook のトリガーになります
filters.allowPrivate	Boolean (optional)	Webhook にプライベートメッセージを送信するかどうか。デフォルト：true
filters.allowGroups	Boolean (optional)	Webhook にグループメッセージを送信するかどうか。デフォルト：true

Webhook ペイロード

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

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

使用方法

実行モード

WhatsApp API サーバー

WhatsApp の機能を REST エンドポイント経由で提供する、スタンドアロンの 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	GET	WhatsApp の接続状態を取得します	なし
/api/contacts	GET	すべての連絡先を取得します	なし
/api/contacts/search	GET	連絡先を検索します	query：検索語
/api/chats	GET	すべてのチャットを取得します	なし
/api/messages/{number}	GET	チャットのメッセージを取得します	limit（クエリ）：メッセージ数
/api/send	POST	メッセージを送信します	number：宛先 message：メッセージの内容
/api/send/media	POST	メディアメッセージを送信します	number：宛先 source：URI スキームを含むメディアソース（URL には http:// または https:// を、ローカルファイルには file:// を使用します） caption（任意）：キャプションテキスト
/api/messages/{messageId}/media/download	POST	メッセージからメディアをダウンロードします	なし

グループ管理

エンドポイント	メソッド	説明	パラメーター
/api/groups	GET	すべてのグループを取得します	なし
/api/groups/search	GET	グループを検索します	query：検索語
/api/groups/create	POST	新しいグループを作成します	name：グループ名 participants：電話番号の配列
/api/groups/{groupId}	GET	特定のグループに関する詳細情報を取得します	なし
/api/groups/{groupId}/messages	GET	グループのメッセージを取得します	limit（クエリ）：メッセージ数
/api/groups/{groupId}/participants/add	POST	グループにメンバーを追加します	participants：電話番号の配列
/api/groups/send	POST	グループにメッセージを送信します	groupId：グループ ID message：メッセージの内容

AI 統合

Claude Desktop の統合

オプション 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 Desktop を再起動します

6. Claude のインターフェースから WhatsApp の機能を利用できるようになります

アーキテクチャ

このプロジェクトは、関心事を明確に分離した構成になっています。

コンポーネント

1. WhatsAppService：WhatsApp とやり取りするための中核となるビジネスロジック
2. WhatsAppApiClient：WhatsApp API に接続するためのクライアント
3. API Router：REST API 用の Express ルート
4. MCP Server：Model Context Protocol の実装

デプロイオプション

1. WhatsApp API Server：スタンドアロンの REST API サーバー
2. MCP Server (Standalone)：WhatsApp Web への直接接続
3. MCP Server (API Client)：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 を使用しています。ワークフローでは、以下の処理を実行します。

1. バージョンの更新（patch、minor、または major）
2. バージョンの前に「v」を付けて Git タグを作成（例：v0.2.1）
3. GitHub シークレットを使用して npm に公開

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

1. GitHub リポジトリの「Actions」タブに移動します
2. 「Publish Package」ワークフローを選択します
3. 「Run workflow」をクリックします
4. バージョンの更新タイプ（patch、minor、または major）を選択します
5. 「Run workflow」をクリックして公開プロセスを開始します

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

トラブルシューティング

Claude Desktop の連携に関する問題

• Claude では wweb-mcp をスタンドアロンのコマンドモードで起動できません。Claude は複数のプロセスを何度も起動し、各 wweb-mcp は同じ WhatsApp 認証を共有できない puppeteer セッションを開く必要があるためです。この制約に対応し、Claude と適切に連携できるよう、アプリを MCP モードと API モードに分割しました。

機能

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

今後の機能

• すべてのメディアファイル形式（動画、音声、ドキュメント）の送信に対応
• よく使われるシナリオ向けのメッセージテンプレートの拡充
• 高度なグループ管理機能
• 連絡先の管理（連絡先の追加・削除）
• エラー処理と復旧機能の強化

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

プルリクエストでは、以下を確認してください：

• 既存のコードスタイルに従っていること
• 適切なテストが含まれていること
• 必要に応じてドキュメントが更新されていること
• 変更内容が詳しく説明されていること

依存関係

WhatsApp Web.js

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

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

ログ

WhatsApp Web MCP には、Winston で構築された堅牢なログシステムが含まれています。ログシステムでは、以下を利用できます。

• 複数のログレベル（error、warn、info、http、debug）
• 色分けされたログのコンソール出力
• API エンドポイントの HTTP リクエスト／レスポンスのログ記録
• 構造化されたエラー処理
• 環境に応じたログレベル（開発環境と本番環境）
• MCP コマンドモードで実行する場合、すべてのログを stderr に出力

ログレベル

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

1. error - アプリケーションの動作を妨げる重大なエラー
2. warn - アプリケーションは停止しませんが、注意が必要な警告
3. info - アプリケーションの状態やイベントに関する一般情報
4. http - HTTP リクエスト／レスポンスのログ記録
5. debug - 詳細なデバッグ情報

ログレベルの設定

--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 で実行している場合）では、ロガーがテストに適した動作に自動で調整されます。