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.

---

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=
PORT=4000
MCP_PORT=8000

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

Verify connectivity with WhatsApp Cloud API.

---

8. Security

• Validate Meta webhook signature (optional v1).
• Restrict MCP tool usage to authenticated WebSocket clients.
• Sanitize user inputs.
• Never log tokens.

---

9. Documentation Requirements

Setup Instructions

1. Install Dependencies

   npm install
   

2. Configure Environment Copy .env.example to .env and fill in your Meta WhatsApp API credentials.

   cp .env.example .env
   

3. Run Locally

   npm run dev
   

   Server will start on port 4000 (HTTP) and expose MCP on WebSocket.

4. Configure Webhook

   • Expose your local server using ngrok or similar: ngrok http 4000
   • In Meta App Dashboard, set Webhook URL to https://<your-ngrok-url>/webhook
   • Set Verify Token to match META_VERIFY_TOKEN in .env

Docker Usage

docker build -t whatsapp-mcp .
docker run -p 4000:4000 --env-file .env whatsapp-mcp

Example Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/path/to/.env", "whatsapp-mcp"]
    }
  }
}

(Note: For local dev without docker, point to the build output)

10. Contact

For any inquiries or similar projects, please contact: marcelo@marcelomarchetti.com