mcp-whatsapp-cloud

@codespar/mcp-whatsapp-cloud

WhatsApp Cloud API 用の MCP サーバーです。Meta 公式の WhatsApp Business API で、Meta のインフラストラクチャ上でセルフホストされます。

Meta との直接連携。 仲介業者もプロバイダーの上乗せ料金もありません。承認済みの WhatsApp Business Account（WABA）を持ち、Meta 直結の料金と、会話、料金カテゴリ、テンプレートのライフサイクルを完全に管理したい事業者向けです。

このカタログにある WhatsApp サーバー

サーバー	概要	選択するケース
whatsapp-cloud（このサーバー）	Meta Cloud API との直接連携	承認済み WABA を持つ大規模事業者。大規模利用時のコストを抑え、中間手数料を回避できます
z-api	Meta Cloud API のラッパー	簡単な導入、即時の QR ペアリング、追加のヘルパー機能
evolution-api	オープンソースのラッパー	セルフホスト可能、コミュニティ主導
take-blip	ブラジルの BSP ラッパー	ブラジルのエンタープライズ向け、CCaaS 機能
zenvia	ブラジルの BSP ラッパー	ブラジルのオムニチャネル（SMS ＋ WhatsApp）

ツール（22）

ツール	目的
send_text_message	プレーンテキストメッセージを送信します。
send_template_message	承認済みのメッセージテンプレートを送信します。
send_media_message	画像、動画、ドキュメント、または音声を送信します。
send_interactive_message	インタラクティブメッセージ（返信ボタンまたはリスト）を送信します。
send_interactive_cta_url	CTA URL ボタンを 1 つ含むインタラクティブメッセージを送信します。
send_interactive_flow	WhatsApp Flow メッセージを送信します。
send_location_message	緯度・経度と、任意の名前・住所を指定して位置情報を送信します。
send_contacts_message	1 件以上の連絡先カード（vCard 形式）を送信します。
send_reaction_message	受信済みまたは送信済みのメッセージに絵文字リアクションを送信します。
send_typing_indicator	受信したメッセージに対して入力中インジケーターを表示します。
mark_message_as_read	受信メッセージを既読にし、送信者に青い二重チェックマークを表示します。
upload_media	メディアファイルをアップロードし、send_media_message で再利用できる media_id を取得します。
retrieve_media_url	media_id を有効期間の短いダウンロード URL に変換します。
delete_media	ID を指定して、アップロード済みメディアアセットを削除します。
list_templates	WhatsApp Business Account のメッセージテンプレートを一覧表示します。
create_template	新しいテンプレートを Meta の審査に提出します。
delete_template	名前を指定して、WABA のメッセージテンプレートを削除します。
get_business_profile	設定済みの電話番号の WhatsApp ビジネスプロフィール（概要、説明、メールアドレス、ウェブサイト、業種、住所）を読み取ります。
update_business_profile	設定済みの電話番号のビジネスプロフィールを更新します。
list_phone_numbers	WhatsApp Business Account に登録されているすべての電話番号を、表示名、品質評価などを含めて一覧表示します。
request_verification_code	設定済みの電話番号に SMS または音声通話で認証コードを送信するよう Meta にリクエストします。
verify_code	request_verification_code の後に SMS または音声通話で受け取った認証コードを送信します。

インストール

npm install @codespar/mcp-whatsapp-cloud

環境

WHATSAPP_ACCESS_TOKEN="EAAG..."           # required (secret) — Meta system-user token
WHATSAPP_PHONE_NUMBER_ID="1234567890"     # required — WABA phone number id
WHATSAPP_BUSINESS_ACCOUNT_ID="9876543210" # required — WABA id (for templates)
WHATSAPP_GRAPH_VERSION="v21.0"            # optional — Meta bumps quarterly

認証

Graph API に対するベアラートークンを使用します。Meta Business Manager の永続的なシステムユーザートークンを使用してください。ユーザーアクセストークンは有効期限が切れるため、本番環境で問題が発生します。

Authorization: Bearer <WHATSAPP_ACCESS_TOKEN>

メッセージ送信のルール（重要）

• カスタマーサービスウィンドウ — ユーザーから最後にメッセージが届いてから 24 時間は、任意の種類のメッセージを自由に送信できます。
• 事業者発信のメッセージ — ウィンドウの終了後は、承認済みのテンプレートを送信する必要があります。名前、言語、コンポーネントを指定して send_template_message を使用してください。
• テンプレート — create_template で作成し、Meta の承認（数分から数時間）を待ってから使用してください。
• 電話番号は先頭の + を除いた E.164 形式で指定します（例：5511999999999）。

メディア

方法は 2 つあります。

1. 公開 URL — send_media_message に link を渡します。最も手早い方法ですが、Meta は送信のたびに取得します。
2. アップロード済みの media_id — upload_media を一度呼び出し、以降の送信で id を再利用します。カタログアセットに推奨されます。

アップロード済みメディアの有効期限は約 30 日です。

インタラクティブメッセージ

send_interactive_message は、完全な形式の interactive オブジェクトを必要とします。ボタンのペイロードの例：

{
  "type": "button",
  "body": { "text": "Confirma seu pedido?" },
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "confirm", "title": "Confirmar" } },
      { "type": "reply", "reply": { "id": "cancel", "title": "Cancelar" } }
    ]
  }
}

リストのペイロードについては、Cloud API のインタラクティブリファレンスを参照してください。

実行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-whatsapp-cloud

# HTTP (for server-to-server)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-whatsapp-cloud

エンタープライズ

エージェントの決済にガバナンス、予算上限、監査証跡が必要ですか？CodeSpar Enterprise は、これらの MCP サーバーにポリシーエンジン、決済ルーティング、コンプライアンステンプレートを追加します。

ライセンス

MIT