MCP Evolution API

MCP Evolution API

Evolution API と連携し、WhatsApp の自動化を実現する Claude 向け Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーを使用すると、Claude は Evolution API を通じて WhatsApp と連携でき、次のような機能を利用できます。

• WhatsApp インスタンスの管理
• さまざまな種類のメッセージの送信
• 連絡先やグループの操作
• Webhook と設定の構成

📂 プロジェクト構成

mcp-evo-api/
├── src/
│   ├── tools/          # MCP tools implementation for Evolution API
│   ├── utils/          # Shared utilities, including Evolution API client
│   ├── main.ts         # Server entry point
│   └── types.ts        # Shared type definitions
├── scripts/            # Helper scripts
├── biome.json          # Linting configuration
├── tsconfig.json       # TypeScript configuration
├── docker-compose.yml  # Docker Compose configuration
├── Dockerfile          # Docker build configuration
└── package.json        # Project dependencies

🚀 クイックセットアップ

環境のセットアップ

Evolution API の認証情報を記載した .env ファイルを作成します。

EVOLUTION_API_URL=https://evo-api.decisao.ai/
EVOLUTION_API_KEY=REPLACE_WITH_YOUR_REAL_KEY

注：API URL とキーをご指定いただいています。セキュリティのため、実際の API キーをリポジトリにコミットしたり、公開したりしないでください。本番環境では、ローカルの .env ファイルまたはシークレットマネージャーを使用してください。

📋 デプロイオプション

環境	手順	コマンド
ローカル開発	1. クローンしてインストール 2. 開発モードで実行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run dev
ローカル本番環境	1. クローンしてインストール 2. ビルドして実行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api && bun install bun run build && bun run dist/main.js
Docker Compose	Docker Compose で実行	git clone https://github.com/aiteks-ltda/mcp-evo-api.git && cd mcp-evo-api docker-compose up -d
Docker	コンテナをビルドして実行	docker run -d -p 3000:3000 -e EVOLUTION_API_URL=yoururl -e EVOLUTION_API_KEY=yourkey --name mcp-evo-api ghcr.io/aiteks-ltda/mcp-evo-api:latest

Claude Desktop の設定

Claude Desktop の設定ファイル（通常は ~/Library/Application Support/Claude/claude_desktop_config.json にあります）に、次の内容を追加します。

{
  "mcpServers": {
    "evo-api": {
      "command": "node",
      "args": [
        "/path/to/your/mcp-evo-api/dist/main.js"
      ]
    }
  }
}

Docker でデプロイする場合：

{
  "mcpServers": {
    "evo-api": {
      "url": "http://localhost:3000"
    }
  }
}

📊 実装状況

カテゴリ	実装済み	実装待ち
コア API	✅ 情報を取得 ✅ インスタンスを作成 ✅ インスタンス一覧を取得 ✅ インスタンスに接続 ✅ インスタンスを再起動 ✅ 接続状態を確認 ✅ インスタンスからログアウト ✅ インスタンスを削除 ✅ プレゼンスを設定	❌ WhatsApp を確認
Webhook と設定	✅ Webhook を設定 ✅ Webhook を検索 ✅ 設定を指定 ✅ 設定を検索
メッセージング	✅ テキストメッセージを送信 ✅ ステータスを送信 ✅ メディアを送信 ✅ WhatsApp オーディオを送信 ✅ スタンプを送信 ✅ 位置情報を送信 ✅ 連絡先を送信 ✅ リアクションを送信 ✅ 投票を送信 ✅ リストを送信 ✅ ボタンを送信	❌ メッセージを既読にする ❌ メッセージを未読にする ❌ チャットをアーカイブする ❌ 全員のメッセージを削除する ❌ メッセージを更新する ❌ プレゼンスを送信（チャット制御）
チャットと連絡先	✅ 連絡先を検索 ✅ チャットを検索	❌ ブロック状態を更新 ❌ プロフィール画像の URL を取得 ❌ Base64 を取得 ❌ メッセージを検索 ❌ ステータスメッセージを検索
グループ	✅ JID でグループを検索 ✅ すべてのグループを取得 ✅ グループメンバーを検索	❌ グループを作成 ❌ グループ画像を更新 ❌ グループの件名を更新 ❌ グループの説明を更新 ❌ 招待コードを取得 ❌ 招待コードを無効化 ❌ グループ招待を送信 ❌ 招待コードでグループを検索 ❌ グループメンバーを更新 ❌ グループ設定を更新 ❌ エフェメラル設定を切り替え ❌ グループから退出
プロフィール設定		❌ ビジネスプロフィールを取得 ❌ プロフィールを取得 ❌ プロフィール名を更新 ❌ プロフィールのステータスを更新 ❌ プロフィール画像を更新 ❌ プロフィール画像を削除 ❌ プライバシー設定を取得 ❌ プライバシー設定を更新
ボット連携		❌ Typebot 連携 ❌ OpenAI 連携 ❌ Evolution Bot ❌ Dify Bot ❌ Flowise Bot
その他の連携		❌ Chatwoot ❌ Websocket ❌ SQS ❌ RabbitMQ

詳細については、Evolution API のドキュメントを参照してください。

例

• examples/hono-bun/ - Bun 向けの小規模な Hono サーバー（保存済みの例）です。実行手順については、examples/hono-bun/README.md を参照してください。