概要

このプロジェクトでは、標準化されたMCPツールを使用して、WhatsApp Cloud APIをLMエージェントに公開するMCP Serverのバージョンを定義しています。

目標: 最小限、クリーン、生産準備のベースラインを提供しているため、開発者はゼロ複雑さでAIエージェント内のWhatsAppメッセージングを使用することができます。

お問い合わせ

クイックスタート

1。 環境テンプレートをコピーし、メタ認証情報を記入します。

MCP_AUTH_TOKENを強力なランダムシークレットにセットする - MCP WebSocket サーバは起動を拒否します。 2. 依存関係を取付けて下さい:

3. サーバーをローカルで動かして下さい:

ヒント: MCP ツールのみをローカルでテストしている場合は、[.env] で有効な WhatsApp Cloud API 認証情報を使用します。 Webhook のみのテストでは、プレースホルダーの値を使用して、インカムのペイロードをシミュレートできます。

1. 目的

• 軽量MCPサーバー(TypeScript + Node.js)を作成します。
• WhatsAppクラウドAPI機能をツールとして公開します。
• Webhookの検証のためのヘルパーを提供して下さい。
• 単一のコマンド(Docker + local dev)でデプロイ可能。

お問い合わせ

2. テックスタック

• Node.js 20+
• TypeScript
• HTTP + Webhooks の Express* (または Fastify )
• MCPサーバーSDK
• Axios アウトバウンド WhatsApp API リクエスト

WhatsApp Cloud API MCP Server – Spec v1.0

Overview

This project defines version 1.0 of an MCP Server that exposes the WhatsApp Cloud API to LLM agents through standardized MCP tools.

Goal: Provide a minimal, clean, production-ready baseline so developers can use WhatsApp messaging inside AI agents with zero complexity.

---

Quick Start

1. Copy the environment template and fill in your Meta credentials:

   cp .env.example .env
   

   Set MCP_AUTH_TOKEN to a strong random secret as well - the MCP WebSocket server refuses to start without it.
2. Install dependencies:

   npm install
   

3. Run the server locally:

   npm run dev
   

Tip: if you’re testing only the MCP tools locally, use valid WhatsApp Cloud API credentials in .env. For webhook-only testing, you can use placeholder values while simulating incoming payloads.

1. Objectives

• Create a lightweight MCP server (TypeScript + Node.js).
• Expose WhatsApp Cloud API functionalities as tools.
• Provide helpers for webhook verification.
• Be deployable with a single command (Docker + local dev).

---

2. Tech Stack

• Node.js 20+
• TypeScript
• Express (or Fastify) for HTTP + webhooks
• MCP Server SDK
• Axios for outbound WhatsApp API requests
• WebSocket for MCP transport (mandatory)
• Dotenv for configs
• Pino or console logging

---

3. Project Structure (v1.0)

/src
  /mcp
    server.ts
  /whatsapp
    client.ts
    webhook.ts
  /config
    env.ts
  index.ts
.env.example
mcp.json
package.json
README.md

---

4. Environment Variables

Required:

META_WHATSAPP_TOKEN=
META_WHATSAPP_PHONE_ID=
META_WHATSAPP_WABA_ID=
META_VERIFY_TOKEN=
MCP_AUTH_TOKEN=
PORT=4000
MCP_PORT=8000

MCP_AUTH_TOKEN is the shared secret that authenticates MCP WebSocket clients. The server exits on startup if it is missing.

Optional:

LOG_LEVEL=debug

---

5. WhatsApp Cloud API Endpoints to Support (v1.0)

The MCP server will call these official endpoints:

Send Text Message

POST /v18.0/{PHONE_ID}/messages

Send Template Message

POST /v18.0/{PHONE_ID}/messages

Get Media URL

GET /v18.0/{MEDIA_ID}

Download Media

GET {MEDIA_URL}

Health Check

GET /v18.0/{PHONE_ID}

---

6. Webhook Handling

Expose:

GET  /webhook (verification)

Features:

• Validate hub.verify_token

---

7. MCP Tools (v1.0)

Tools exposed to agents:

1. send_text_message

Send a simple text message to a WhatsApp user.

Params:

{
  "to": "string",
  "text": "string"
}

2. send_template_message

Send a WhatsApp template message.

Params:

{
  "to": "string",
  "template_name": "string",
  "language": "string",
  "components": []
}

3. get_media

Retrieve a media file by MEDIA_ID.

Params:

{
  "media_id": "string"
}

4. health_check