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)

Tool	Description
whatsapp_send_text	Send text messages
whatsapp_send_template	Send approved template messages (required for initiating conversations)
whatsapp_send_image	Send images via URL
whatsapp_send_document	Send documents (PDF, DOCX, etc.) via URL
whatsapp_send_location	Send location pins
whatsapp_send_contact	Send contact cards
whatsapp_send_reaction	React to messages with emoji
whatsapp_send_buttons	Send interactive reply buttons (up to 3)
whatsapp_send_list	Send interactive list menus
whatsapp_mark_as_read	Mark messages as read (blue checkmarks)
whatsapp_get_business_profile	Retrieve your business profile
whatsapp_update_business_profile	Update business profile fields
whatsapp_list_templates	List approved message templates

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