개요

이 프로젝트는 버전 1.0의 MCP Server 를 정의하여 WhatsApp Cloud API 를 표준 MCP 도구를 통해 LLM 에이전트로 노출합니다.

Goal: 최소한, 청결한, 생산 ready 지하실을 제공하십시오 그래서 개발자는 0개의 복잡성을 가진 AI 대리인 안쪽에 WhatsApp 메시징을 사용할 수 있습니다.

---

빠른 시작

1. 환경 템플릿을 복사하고 Meta credentials에 채우십시오.

MCP_AUTH_TOKEN]를 강력한 임의 비밀으로 설정 - MCP WebSocket 서버가 없는 시작을 거부합니다. 2. 의존성 설치:

3. 서버 로컬로 실행:

팁 : 로컬 MCP 도구 만 테스트하면 .env에서 유효한 WhatsApp Cloud API 자격 증명을 사용하십시오. 웹훅 전용 테스트를 위해, 들어오는 페이로드를 시뮬레이션하면서 placeholder 값을 사용할 수 있습니다.

1. 목표

• 경량 MCP 서버를 만듭니다 (TypeScript + Node.js).
• 도구로 WhatsApp Cloud API 기능 노출.
• webhook 검증을 위한 도움말 제공
• 단일 명령 (Docker + local dev)로 배포할 수 있습니다.

---

2. 기술 스택

• **Node.js 20 + **
• **TypeScript **
• Express (또는 Fastify) HTTP + 웹훅
• 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