WhatsApp MCP Server

An MCP (Model Context Protocol) server that enables LLMs to interact with WhatsApp via the official WhatsApp Cloud API by Meta.

Features

Messaging Tools (13 tools)

Related MCP server: WAHA MCP Server

Prerequisites

1. Meta Developer Account — Register at https://developers.facebook.com

2. WhatsApp Business App — Create a Meta app with the WhatsApp use case

3. Access Token — Generate from the WhatsApp API Setup panel

4. Phone Number ID — Found in the WhatsApp API Setup panel

Getting Your Credentials

1. Go to Meta for Developers

2. Create or select your app → Add the WhatsApp use case

3. In the WhatsApp API Setup panel, note:

   • Phone Number ID (numeric ID under your test number)

   • WhatsApp Business Account ID (for template operations)

4. Generate a Temporary Access Token (valid 24h) or set up a System User for a permanent token

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

# Required
export WHATSAPP_ACCESS_TOKEN="your_access_token"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"

# Optional
export WHATSAPP_BUSINESS_ACCOUNT_ID="your_waba_id"  # Required for template operations
export WHATSAPP_API_VERSION="v23.0"                  # Default: v23.0
export TRANSPORT="stdio"                              # "stdio" (default) or "http"
export PORT="3000"                                    # HTTP port (default: 3000)

3. Build & Run

npm run build
npm start

Usage with Claude Desktop

Add this to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "your_token",
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_waba_id"
      }
    }
  }
}

Usage as HTTP Server

TRANSPORT=http PORT=3000 npm start

The server exposes:

• POST /mcp — MCP endpoint (Streamable HTTP)

• GET /health — Health check

Important Notes

24-Hour Messaging Window

WhatsApp enforces a 24-hour customer service window. You can only send free-form messages (text, image, etc.) to users who have messaged you within the last 24 hours. Outside this window, you must use approved template messages to initiate contact.

Phone Number Format

Always use international format without the + prefix (e.g., 353851234567 for an Irish number, 14155551234 for a US number).

Rate Limits

The Cloud API supports up to 80 messages per second for standard tier. Monitor your usage in the Meta Business Manager.

License

MIT