Обзор

Этот проект определяет версию 1.0 сервера MCP, которая предоставляет WhatsApp Cloud API агентам LLM через стандартизированные инструменты MCP.

Цель: обеспечить минимальный, чистый, готовый к производству базовый уровень, чтобы разработчики могли использовать обмен сообщениями WhatsApp внутри агентов ИИ с нулевой сложностью.

Быстрый старт

1.Копируйте шаблон окружения и заполните свои мета-удостоверения:

Установите MCP_AUTH_TOKEN также сильный случайный секрет - MCP WebSocket Сервер отказывается начинать работу без него. 2. Установить зависимости:

3.Запустите сервер локально:

Совет: если вы тестируете только инструменты MCP локально, используйте действительные учетные данные WhatsApp Cloud API в .env. Для тестирования только для веб-хуков вы можете использовать значения заполнителей при моделировании входящих полезных нагрузок.

1 Цели

Создайте легкий MCP-сервер (TypeScript + Node.js). Раскройте функции WhatsApp Cloud API в качестве инструментов.

• Предоставьте помощников для проверки веб-хук. Развертывайтесь с одной командой (Docker + local dev).

#2 - Технический стек

Node.js 20+ TypeScript Express (или Fastify) для HTTP + webhooks MCP Server SDK Axios для исходящих запросов API WhatsApp

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