Skip to main content
Glama
enesjakozh
pnizer

WhatsApp Web MCP

by pnizer
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

WhatsAppウェブMCP

PRチェック

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

概要

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はプラットフォーム上でボットや非公式クライアントを許可していないため、完全に安全であるとは考えられません。

学習リソース

WhatsApp Web 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コードを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を使用する

  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台のマシンで実行する

発達

プロジェクト構造

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 Secretsを使ってnpmに公開する

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

  1. GitHubリポジトリのアクションタブに移動します

  2. 「パッケージを公開」ワークフローを選択する

  3. 「ワークフローを実行」をクリックします

  4. バージョン増分タイプ（パッチ、マイナー、メジャー）を選択します

  5. 「ワークフローを実行」をクリックして公開プロセスを開始します

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

トラブルシューティング

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

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

特徴

  • メッセージの送受信

  • メディアメッセージの送信（画像のみ）

  • メッセージからメディアをダウンロードする（画像、音声、ドキュメント）

  • グループチャット管理

  • 連絡先の管理と検索

  • メッセージ履歴の取得

今後の機能

  • すべてのメディアファイルタイプ（ビデオ、オーディオ、ドキュメント）の送信をサポート

  • 一般的なシナリオ向けの強化されたメッセージ テンプレート

  • 高度なグループ管理機能

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

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

貢献

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

npm start -- --log-level=debug

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

wweb-mcp --log-level=debug

コマンドモードログ

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

テスト環境

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/pnizer/wweb-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server