概述

本项目定义了1.0版本的MCP服务器，通过标准化MCP工具向LLM代理开放WhatsApp Cloud API。

目标：提供一个简洁、干净、适合生产的基线，使开发者能够在AI代理内无复杂度地使用WhatsApp消息。

---

快速启动

1. 复制环境模板并填写你的Meta资历：

也将MCP_AUTH_TOKEN设置为一个强随机秘密——MCP WebSocket 服务器拒绝在没有它的情况下开始。 2. 安装依赖：

3. 本地运行服务器：

提示：如果你只在本地测试MCP工具，请使用.env中的有效WhatsApp Cloud API凭证。对于仅对webhook进行测试，你可以在模拟进入负载时使用占位符值。

1.目标

• 创建一个轻量级MCP服务器（TypeScript + Node.js）。
• 将WhatsApp Cloud API功能作为工具公开。
• 提供Webhook验证的辅助工具。
• 只需一个命令即可部署（Docker + 本地开发）。

---

2.技术栈

• Node.js 20+
• TypeScript
• Express（或 Fastify）用于 HTTP + webhook
• 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