WhatsApp MCP Server with Wati API

Wati API v3 を使用した WhatsApp MCP サーバー

ヒント

Wati には公式のホスト型 MCP サーバーが用意されています。 インストールも API キーも不要です。https://mcp.wati.io/mcp（EU：https://eu-mcp.wati.io/mcp）に接続し、OAuth でサインインしてください。Claude、ChatGPT、Meta Muse、Cursor などで利用でき、Astra AI エージェントも管理できます。セットアップガイド：wati-io/wati-mcp · サポート記事。必要な場合は、このセルフホスト可能なサーバーも引き続き利用できます。

これは、Wati API v3 を使用して WhatsApp を操作する Model Context Protocol（MCP）サーバーです。

Claude などの AI アシスタントを通じて、WhatsApp の会話、連絡先、テンプレート、キャンペーン、チャネルを管理できます。メッセージの検索と閲覧、テキストやファイルの送信、連絡先の管理、ワークフローの自動化をすべて MCP ツール経由で行えます。

このプロジェクトやその他のプロジェクトに関する更新情報を受け取るには、こちらにメールアドレスを入力してください

v0.2.0 の新機能

破壊的変更： このリリースでは、従来の Wati v1 API から v3 API（/api/ext/v3/*）に移行します。

変更点

• API v3 への移行 — すべてのエンドポイントを /api/ext/v3/* パスに更新
• URL スキーム — テナント ID は URL パスに含まれなくなり、Bearer トークンから解決されます
• WATI_TENANT_ID がオプションに — マルチチャネル設定（Channel:PhoneNumber によるターゲティング）でのみ必要です
• 新しいツール： list_contacts、get_contact、add_contact、update_contacts、get_contact_count、assign_contact_teams、send_file_via_url、send_interactive（ボタン＋リスト）、assign_operator、update_conversation_status、list_templates、get_template、send_template、list_campaigns、get_campaign、list_channels
• 削除されたツール： list_chats、get_chat、get_direct_chat_by_contact、get_contact_chats（list_contacts／get_contact／get_messages に置き換え）
• レスポンス解析の簡素化 — v3 ではレスポンススキーマが標準化されています

移行ガイド

1. WATI_API_BASE_URL を Wati サーバーに設定します（例：https://live-mt-server.wati.io）
2. マルチチャネルターゲティングを使用しない場合は、WATI_TENANT_ID を削除できます
3. ツール呼び出しを更新します：send_message(recipient=...) → send_message(target=...)
4. list_chats／get_chat を list_contacts／get_contact と get_messages に置き換えます

インストール

Smithery 経由でのインストール

npx -y @smithery/cli install @wati-io/wati-mcp-server --client claude

前提条件

• Python 3.11 以降
• Anthropic Claude デスクトップアプリ（または Cursor）
• UV（Python パッケージマネージャー）。curl -LsSf https://astral.sh/uv/install.sh | sh でインストールします
• Wati API へのアクセス（認証トークンが必要です）

手順

1. このリポジトリをクローンします

   git clone https://github.com/wati-io/wati-mcp-server.git
   cd wati-mcp-server
   

2. Wati API を設定します

   サンプル環境ファイルをコピーし、Wati API の認証情報を設定します：

   cp .env.example .env
   # Edit .env with your Wati API credentials
   

   必須：

   • WATI_API_BASE_URL：Wati API のベース URL（例：https://live-mt-server.wati.io）
   • WATI_AUTH_TOKEN：Wati 認証トークン（ダッシュボードで取得した Bearer トークン）

   オプション：

   • WATI_TENANT_ID：Wati テナント ID（マルチチャネル設定でのみ必要です）

3. MCP サーバーに接続します

   以下の JSON を適切な {{PATH}} の値に置き換えてコピーします：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}",
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/wati-mcp-server",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   Claude の場合は、これを claude_desktop_config.json として次の場所に保存します：

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   Cursor の場合は、これを mcp.json として次の場所に保存します：

   ~/.cursor/mcp.json
   

4. Claude Desktop／Cursor を再起動します

MCP ツール

連絡先

• search_contacts — 名前または電話番号で連絡先を検索します
• list_contacts — ページネーションを使用して連絡先を一覧表示します
• get_contact — 電話番号または ID で連絡先の詳細情報を取得します
• add_contact — 新しい WhatsApp 連絡先を追加します
• update_contacts — 連絡先のカスタムパラメーターを一括更新します
• get_contact_count — 連絡先の総数を取得します
• assign_contact_teams — 連絡先をチームに割り当てます

メッセージと会話

• get_messages — 連絡先との会話メッセージを取得します
• send_message — テキストメッセージを送信します
• send_file — アップロードしてファイル（画像、動画、ドキュメント、音声）を送信します
• send_file_via_url — URLでファイルを送信します（ローカルへのダウンロードは不要です）
• download_media — メッセージからメディアをダウンロードします
• send_interactive — インタラクティブなボタンまたはリストメッセージを送信します
• assign_operator — 会話にオペレーターを割り当てます
• update_conversation_status — 会話のステータスを更新します（open/solved/pending/block）

テンプレート

• list_templates — メッセージテンプレートの一覧を取得します
• get_template — テンプレートの詳細を取得します
• send_template — 宛先にテンプレートメッセージを送信します

キャンペーン

• list_campaigns — ブロードキャストキャンペーンの一覧を取得します
• get_campaign — キャンペーンの詳細と統計情報を取得します

チャネル

• list_channels — 利用可能なWhatsAppチャネルの一覧を取得します

アーキテクチャ

Claude/AI Assistant
    ↕ MCP Protocol (stdio)
Python MCP Server (FastMCP)
    ↕ HTTPS + Bearer Auth
Wati API v3
    ↕
WhatsApp Business

1. ClaudeはMCPプロトコル経由でPython MCPサーバーにリクエストを送信します
2. MCPサーバーはWati v3 APIに認証済みのAPI呼び出しを行います
3. Wati APIはWhatsAppのバックエンドと通信します
4. データはこの経路を通ってClaudeに戻ります

トラブルシューティング

• 認証エラー：WATI_AUTH_TOKEN が有効で、期限切れでないことを確認してください
• 404エラー：WATI_API_BASE_URL が正しいWatiサーバーを指していることを確認してください
• レート制限：Wati APIにはレート制限があります。制限に達した場合は、しばらく待つかWatiサポートにお問い合わせください
• メディアのアップロード失敗：ファイル形式のサポート状況とサイズ制限を確認してください
• uvの権限の問題：PATHに追加するか、実行ファイルのフルパスを使用してください

MCP連携のトラブルシューティングについては、MCPのドキュメントを参照してください。