Whatsapp Business Mcp

WhatsApp MCP サーバー

Meta Cloud API を利用して、Claude、ChatGPT、Cursor、VS Code Copilot、または MCP 対応クライアントから WhatsApp Business テンプレートを管理し、メッセージを送信できます。

できること

テンプレートのライフサイクル全体（作成 → 検証 → 承認 → 送信）に対応する8 つのツールを提供します。

クイックスタート

1. クローンしてインストール

git clone https://github.com/nakulben/whatsapp-mcp.git
cd whatsapp-mcp
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 認証情報を設定

cp .env.example .env

META_ACCESS_TOKEN=your_access_token
META_WABA_ID=your_whatsapp_business_account_id
META_PHONE_NUMBER_ID=your_phone_number_id
META_APP_ID=your_app_id              # Optional, for media uploads
META_API_VERSION=v24.0               # Optional, defaults to v24.0

環境変数は、ローカルの stdio とホスト型のリモートのすべてのモードで使用されます。

認証情報の取得方法: Meta for Developers にアクセスし、アプリを作成または選択して、WhatsApp > API Setup に移動します。

3. MCP クライアントに接続

サーバーは3 つのトランスポートモードに対応しています。

HTTP トランスポートでは、ホスト／ポートをカスタマイズできます。

python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Claude Desktop（stdio — ローカル）

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token",
        "META_WABA_ID": "your_waba_id",
        "META_PHONE_NUMBER_ID": "your_phone_number_id",
        "META_APP_ID": "your_app_id"
      }
    }
  }
}

Claude.ai Web（リモート — streamable-http）

Claude.ai は、カスタムコネクターとしてリモート MCP サーバーに接続します。接続はお使いのマシンではなく、Anthropic のクラウドサーバーから行われます。

1. 環境変数を設定したサーバーを、HTTPS の背後でホストします。

   python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8001
   

2. nginx、Caddy、またはトンネル（ngrok、Cloudflare Tunnel）を使って HTTPS の背後に配置します
3. Claude.ai で Customize > Connectors に移動し、Add custom connector を選択します
4. サーバーの URL（例：https://your-domain.com/mcp/）を入力します
5. Claude は認証なしまたはOAuth ベースのサーバーに対応しています。最も簡単な方法は、認証を空欄にすることです。サーバーは手順 1 で設定した環境変数を使用します。

注: Claude.ai はカスタムリクエストヘッダーに対応していません。サーバーには、環境変数を使って Meta の認証情報を事前に設定する必要があります。ホストされた各サーバーが提供できるのは、1 つの WhatsApp Business Account です。

location /mcp/ {
    proxy_pass http://127.0.0.1:8001/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

ChatGPT（リモート — Responses API）

ChatGPT は、Responses API を通じてリモート MCP サーバーに対応しています。Streamable HTTP と SSE の両方のトランスポートをサポートしています。

オプション 1 — 環境変数でサーバーに事前設定（最も簡単）：

from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

オプション 2 — Bearer トークンを使ったリクエストごとの認証情報：

Meta の認証情報を base64 JSON としてエンコードし、authorization フィールドに渡します。 OpenAI はこの値を Authorization ヘッダーとして MCP サーバーに転送します。

# Create the token
echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64
# Output: eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=

resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "authorization": "eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

注: ChatGPT はリモート MCP サーバーにのみ対応しています（ローカルの stdio には対応していません）。サーバーは HTTPS 経由でパブリックにアクセスできる必要があります。

Cursor（stdio）

プロジェクトの .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

VS Code Copilot（stdio）

.vscode/mcp.json に追加します：

{
  "servers": {
    "whatsapp": {
      "type": "stdio",
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

リクエストごとの認証情報（直接 HTTP／curl／スクリプト）

プログラムからのアクセスやカスタム MCP クライアントでは、サーバーの環境変数に依存せず、リクエストごとの認証情報を渡すことができます。次の 2 つの方法をサポートしています：

方法 1 — Bearer トークン（推奨）：

Meta の認証情報を含む JSON オブジェクトを Base64 でエンコードします：

# Create the token
TOKEN=$(echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64)

# Use it
curl -H "Authorization: Bearer $TOKEN" https://your-server.com/mcp/ ...

必須フィールド：access_token、phone_number_id、waba_id。任意フィールド：app_id、api_version。

方法 2 — X-Meta- ヘッダー：*

Bearer トークンも X-Meta-* ヘッダーも指定されていない場合、サーバーは環境変数にフォールバックします。

使用例

接続したら、AI アシスタントに話しかけるだけです：

「ヘッダー画像、50% オフについての本文、Shop Now ボタンを含む summer_sale というマーケティングテンプレートを作成して」

「承認済みのテンプレートをすべて一覧表示して」

「注文番号 ORD-456 の order_confirmation テンプレートを +919876543210 に送信して」

「送信する前に、このテンプレートを検証して：...」

「テンプレート ID 123456789 のステータスを確認して」

サポートされているテンプレートタイプ

Meta の API には 2 つのテンプレートカテゴリがあります（Authentication を除く）。各カテゴリには、異なる 構造バリエーションがあり、それぞれ独自のコンポーネント構成と検証ルールがあります。

マーケティングテンプレート

ユーティリティテンプレート

ルーティングの仕組み： create_template を呼び出すと、サーバーはコンポーネントを調べて構造バリエーション（例：cards[] があればカルーセル、CATALOG ボタンがあればカタログ）を自動検出し、適切なバリデーターを適用します。渡すのは category: "MARKETING" または "UTILITY" だけです。バリエーションはコンポーネントの構造から判定されます。

テストの実行

pip install pytest pytest-asyncio
python -m pytest tests/ -v

プロジェクト構成

whatsapp-mcp/
├── whatsapp_mcp/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # Entry point (python -m whatsapp_mcp)
│   ├── config.py            # Environment config loader
│   ├── meta_api.py          # Async Meta Graph API client
│   ├── middleware.py         # ASGI middleware for per-request credentials
│   ├── server.py            # MCP server with 8 tools
│   ├── models/              # Pydantic data models
│   │   ├── body.py          # Body component
│   │   ├── header.py        # Header component (text/image/video/document)
│   │   ├── footer.py        # Footer component
│   │   ├── buttons.py       # Button types (URL, phone, quick reply, etc.)
│   │   ├── buttons_component.py
│   │   ├── enums.py         # Template categories, types, formats
│   │   └── order_models.py  # Order-related models (checkout templates)
│   └── validators/
│       ├── create/          # 12 template creation validators
│       └── send/            # 11 template send validators
├── tests/
│   ├── test_validators.py   # Validator tests
│   ├── test_meta_api.py     # API client tests (mocked HTTP)
│   └── test_tools.py        # MCP tool registration & helper tests
├── .env.example
├── requirements.txt
├── LICENSE                  # MIT
└── ROADMAP.md

要件

• Python 3.10+
• Meta WhatsApp Business Account
• whatsapp_business_messaging および whatsapp_business_management 権限を持つシステムユーザーのアクセストークン

依存関係

ロードマップ

予定されている機能については、ROADMAP.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

Jina Connect が開発 — WhatsApp Business CX プラットフォーム。