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

Install Dependencies
```
npm install
```
Configure Environment Copy .env.example to .env and fill in your Meta WhatsApp API credentials.
```
cp .env.example .env
```
Run Locally
```
npm run dev
```
Server will start on port 4000 (HTTP) and expose MCP on WebSocket.
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

Setup Instructions

Install Dependencies

npm install

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

cp .env.example .env

Run Locally

npm run dev

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

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