Evolution WhatsApp

evolution-whatsapp-mcp

Claude（およびあらゆる MCP クライアント）から WhatsApp を利用できる MCP サーバーです。 Evolution API を介して、メッセージの送受信、メディアの送信、接続の管理を行います。Claude Desktop/Code に追加すると、エージェントが WhatsApp の電話番号に接続して相手とやり取りできるようになります。

クライアントコードは、マルチテナント型クリニック向け SaaS の WhatsApp 統合機能をもとにしています。9 つすべてのツールは、2026 年 10 月に実際の Evolution API 2.3.7 サーバーを使って最後に動作確認されています。

アーキテクチャと実行場所

Claude (Desktop/Code)        evolution-whatsapp-mcp          Evolution API        WhatsApp
     [MCP client]   ──stdio──►   (this package)    ──HTTP──►   (gateway)  ──────►  (phone)

• この MCP サーバーはローカルで必要に応じて実行されます。ホストする必要はありません。 MCP クライアント（Claude Desktop/Code）が stdio 経由で子プロセスとして起動します（npx evolution-whatsapp-mcp）。クライアントが必要としたときに起動し、クライアントを閉じると終了します。開放ポートもデプロイも不要です。
• 常時稼働させておく必要があるのは Evolution API です。 WhatsApp セッションを保持するためです（WhatsApp Web と同様、停止すると電話番号の接続が切れます）。動作を試す場合はローカルで Docker を使って実行し、24 時間 365 日オンラインにしておく必要がある場合（ウェブフック経由でメッセージを受信する場合など）は小規模な VPS で実行してください。このサーバーに必要なのは URL と API キーだけです。
• サーバーはステートレスです。データベースはなく、メッセージも保存しません。MCP クライアントから Evolution API への呼び出しを中継するだけです。

ツール

ツール	説明
send_text	電話番号にテキストメッセージを送信します
send_media	画像／動画／ドキュメント／音声を送信します（URL または base64）
find_chats	インスタンス上の会話を一覧表示します（limit のデフォルトは 50、最大は 200）
find_messages	limit（デフォルトは 50、最大は 200）と page を指定して、電話番号または JID でチャットのメッセージ履歴を読み取ります
create_instance	新しいインスタンス（WhatsApp 接続枠）を作成します
get_qrcode	WhatsApp の電話番号を連携するための QR コード（base64）を取得します
connection_status	インスタンスが接続されているか確認します
disconnect_instance	インスタンスから WhatsApp の電話番号をログアウトします
configure_webhook	インスタンスのウェブフックを公開 URL に設定します

すべてのツールで instance 引数は任意です。省略すると EVOLUTION_DEFAULT_INSTANCE が使用されます。

ツールには MCP アノテーションが付与されています。読み取りツールは読み取り専用としてマークされ、disconnect_instance と configure_webhook は破壊的操作としてマークされるため、クライアントは事前に確認を求めることができます。

find_messages は、9 桁目の数字の有無を問わずブラジルの電話番号を受け付けます。WhatsApp では一部のチャットが短い形式の番号で保存されるため、最初の形式でメッセージが見つからない場合、ツールはもう一方の形式も試します。

前提条件

稼働中の Evolution API サーバー（v2.x）とその API キーが必要です。ローカルで実行する最も簡単な方法は、必要な Postgres と Redis を含む Evolution API v2 のサンプル docker-compose.yml を使うことです。動作を試す場合はローカルの Docker、24 時間 365 日運用する場合はVPSを使用してください。

EVOLUTION_API_KEY=my-secret-key docker compose up -d

http://localhost:8080 で待ち受けます。MCP サーバーを接続するときは、EVOLUTION_API_KEY に同じ値を使用してください（上記を参照）。この compose ファイルは出発点として用意したものであり、本番環境向けの構成ではありません。

インストールと設定

Claude Code では次の1行を実行します。

claude mcp add evolution-whatsapp \
  -e EVOLUTION_API_URL=http://localhost:8080 \
  -e EVOLUTION_API_KEY=your-evolution-api-key \
  -- npx -y evolution-whatsapp-mcp

その他のクライアントでは、MCP クライアントの設定に追加します。Claude Desktop ／ Claude Code（mcpServers 設定）の場合：

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["-y", "evolution-whatsapp-mcp"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_DEFAULT_INSTANCE": "my-whatsapp"
      }
    }
  }
}

環境変数	必須	説明
EVOLUTION_API_URL	はい	Evolution API サーバーのベース URL
EVOLUTION_API_KEY	はい	Evolution API キー（apikey ヘッダーとして送信されます）
EVOLUTION_DEFAULT_INSTANCE	いいえ	ツールで instance が指定されていない場合のデフォルトインスタンス
EVOLUTION_TIMEOUT_MS	いいえ	リクエストごとのタイムアウト（ミリ秒、デフォルトは 30000）
EVOLUTION_READ_ONLY	いいえ	true、1、yes（大文字・小文字は区別しません）を設定すると、send_text、send_media、create_instance、disconnect_instance、configure_webhook が非表示になります。それ以外の値では有効のままです
EVOLUTION_CONFIRM_WRITES	いいえ	true、1、yes（大文字・小文字は区別しません）を設定すると、send_text、send_media、create_instance、disconnect_instance、configure_webhook の実行前に人による確認を待ちます。確認画面を表示できないクライアントでは拒否され、何も送信されません。false、0、no、空の値は無効です（デフォルト）。それ以外の値（ture や on などの入力ミスを含む）は有効として扱われ、stderr に警告が出力されます
EVOLUTION_ALLOWED_NUMBERS	いいえ	send_text と send_media の送信先として許可する番号をカンマ区切りで指定します（例：5511999999999,5521988887777）。空の場合は制限されません。ブラジルの電話番号は9桁目の有無を問わず一致します。このリストを設定すると、グループ JID は拒否されます

LLM がこれらのツールを操作するため、受信メッセージに含まれるプロンプトインジェクションによって、何かを送信するよう指示される可能性があります。EVOLUTION_READ_ONLY と EVOLUTION_ALLOWED_NUMBERS を使って、実行可能な操作を制限できます。

組み込みの制限：find_chats と find_messages では limit（1～200、デフォルトは50）を指定できます。レスポンスが100,000文字を超える場合は、通知を付けて切り詰められます。get_qrcode では、大きすぎる base64 画像を削除し、ペアリングコードを残します。configure_webhook で受け付ける URL は https のみです（localhost、127.0.0.1、[::1] では通常の http も使用できます）。EVOLUTION_API_URL が https でも localhost でもない場合、API キーが暗号化されずに送信されるため、サーバーは stderr に警告を出力します。

書き込み前に確認する

ツールの説明は注意喚起であり、実行を阻止するものではありません。モデルは「接続を再起動する」ために disconnect_instance を呼び出すこともできます。EVOLUTION_CONFIRM_WRITES=true を設定すると、サーバーは各書き込み（send_text、send_media、create_instance、disconnect_instance、configure_webhook）を、モデルが制御できない経路であるクライアントを通じて人が確認するまで保留します。デフォルトでは無効のため、ヘッドレス自動化は引き続き動作します。人が確認に参加する場合は有効にしてください。

人に表示されるのは、操作内容、番号をマスクした宛先（+55 11 9****-9999）、テキストの最大200文字を含む短いプレビューです。メディアの内容と Webhook のパスやクエリ文字列は表示されません。ダイアログのデフォルトは「いいえ」で、120秒間応答を待ちます。明示的な「はい」以外（拒否、キャンセル、タイムアウト、エラー）の場合は何も送信されません。

クライアントの宣言	結果
フォームによる確認（Claude Code の elicitation など）	各書き込みの前に「はい／いいえ」のダイアログを表示
その他すべて（機能なし、URL のみの確認、MCP Apps のみ）	書き込みを isError で拒否し、何も送信しません

MCP Apps クライアント向けの確認カードは、このリリースには含まれていません。Claude Code は MCP Apps をレンダリングしないため（modelcontextprotocol/modelcontextprotocol のクライアントマトリックス、2026-11-03）、ダイアログを使用します。一部の Claude Code バージョンでは、確認フォームが自動的に拒否されるとの報告があります。その場合、書き込みは拒否され、送信されることはありません。

この機能は他の制限と併用されます。まず EVOLUTION_ALLOWED_NUMBERS が確認され（リスト外の番号は、確認を求めずに拒否されます）、EVOLUTION_READ_ONLY が有効な場合は、確認対象となる書き込みツール自体がありません。

使用例（最初から最後まで）

Claude に依頼します：

1. 「my-whatsapp という名前の WhatsApp インスタンスを作成して、QR コードを表示してください。」 → create_instance + get_qrcode（スマートフォンでスキャンします）。
2. 「接続されていますか？」 → connection_status。
3. 「+55 11 99999-9999 に『Your appointment is confirmed』と送信してください。」 → send_text。
4. 「相手からの返信は何でしたか？」 → find_messages。

トラブルシューティング

症状	原因と対処方法
HTTP 401 / Unauthorized	EVOLUTION_API_KEY がサーバーの AUTHENTICATION_API_KEY と一致していません。
タイムアウト / fetch failed	URL が間違っているか、Evolution API が停止しています。ブラウザーで EVOLUTION_API_URL を開いてください。サーバーの応答が遅い場合は、EVOLUTION_TIMEOUT_MS の値を大きくしてください。
送信に失敗する、インスタンスが open ではない	インスタンスが接続されていません。connection_status を実行し、続けて get_qrcode を実行して、スマートフォンでスキャンしてください（WhatsApp > リンク済みデバイス）。
ブラジルの電話番号で find_messages が何も返さない	WhatsApp では、チャットの電話番号に 9 桁目の数字が含まれる場合と含まれない場合があります。このツールは両方を試します。国番号（55）が含まれていることを確認してください。
number must be a phone with 8 to 15 digits	国番号を含む電話番号全体を渡すか、@ を含む JID を渡してください。
Webhook URL が拒否される	configure_webhook では https が必要です（localhost、127.0.0.1、[::1] の場合に限り http も使用できます）。localhost.evil.com のような、よく似たホスト名は拒否されます。
ツール一覧に send_text がない	EVOLUTION_READ_ONLY が有効になっています。設定を解除するか、false に設定してください。
Recipient is not in EVOLUTION_ALLOWED_NUMBERS	その電話番号は許可リストに登録されていません。追加するか、変数を空にしてください。
応答の末尾に truncated: use limit/page と表示される	ペイロードが 100,000 文字を超えています。limit の値を小さくするか、ページごとに読み取ってください。

ディレクトリ掲載情報

公式 MCP レジストリ向けのメタデータは server.json に、Smithery向けのメタデータは smithery.yaml にあります。 Glama は、この README と package.json から公開されている GitHub MCP サーバーをインデックス化するため、両方を正確に保ってください。

開発

npm install
npm run build      # tsc → dist/
npm test           # vitest (mocks the Evolution API; no server needed)
npm run lint       # tsc --noEmit

MCP Inspector でサーバーをローカルに確認します：

EVOLUTION_API_URL=http://localhost:8080 EVOLUTION_API_KEY=key \
  npx @modelcontextprotocol/inspector node dist/index.js

仕組み

薄い REST クライアント（src/evolution.ts）が Evolution エンドポイントをラップし、apikey ヘッダーで認証します。src/tools.ts は各操作を zod の入力スキーマを持つ MCP ツールとして登録し、 src/index.ts はそれらを stdio 経由で提供します。

ライセンス

MIT © Ewerton Silva