Which integrations are available for this server?

Integrates with the Meta Cloud API (v24.0) to enable WhatsApp Business operations, using Meta access tokens and Business Account credentials for authentication, template management, and message sending capabilities. Manages WhatsApp Business templates and messaging via the Meta Cloud API, providing tools to create, validate, list, delete, and check status of templates, as well as send template messages (including bulk sends) to phone numbers. Supports marketing and utility template types with various structural variants including carousels, catalogs, limited-time offers, and order details.

WhatsApp MCP Server

Manage WhatsApp Business templates and send messages from Claude, ChatGPT, Cursor, VS Code Copilot, or any MCP-compatible client — powered by the Meta Cloud API.

What It Does

Tool	Description
`validate_template`	Validate a template payload before submitting to Meta
`create_template`	Submit a template for Meta approval
`list_templates`	List templates with optional filters (status, category, name)
`get_template_detail`	Get full details of a template by ID
`check_template_status`	Quick status check for a template
`delete_template`	Delete a template by name
`send_template_message`	Send an approved template to a phone number
`send_bulk_template_messages`	Send an approved template to multiple phone numbers

8 tools covering the full template lifecycle: create → validate → approve → send.

Quick Start

1. Clone & Install

git clone https://github.com/nakulben/whatsapp-mcp.git
cd whatsapp-mcp
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure Credentials

cp .env.example .env

META_ACCESS_TOKEN=your_access_token
META_WABA_ID=your_whatsapp_business_account_id
META_PHONE_NUMBER_ID=your_phone_number_id
META_APP_ID=your_app_id              # Optional, for media uploads
META_API_VERSION=v24.0               # Optional, defaults to v24.0

Environment variables are used by all modes — local stdio and hosted remote.

How to get these? Go to Meta for Developers, create or select your app, navigate to WhatsApp > API Setup.

3. Connect to Your MCP Client

The server supports 3 transport modes:

Transport	Command	Used By
`stdio` (default)	`python -m whatsapp_mcp`	Claude Desktop, Cursor, VS Code, Windsurf
`sse`	`python -m whatsapp_mcp --transport sse`	Legacy remote clients
`streamable-http`	`python -m whatsapp_mcp --transport streamable-http`	Claude.ai, ChatGPT, newer MCP clients

For HTTP transports, you can customize host/port:

python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Claude Desktop (stdio — local)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token",
        "META_WABA_ID": "your_waba_id",
        "META_PHONE_NUMBER_ID": "your_phone_number_id",
        "META_APP_ID": "your_app_id"
      }
    }
  }
}

Claude.ai Web (remote — streamable-http)

Claude.ai connects to remote MCP servers as custom connectors. The connection originates from Anthropic's cloud servers, not from your machine.

Host the server with env vars configured, behind HTTPS:

python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8001

Put it behind HTTPS using nginx, Caddy, or a tunnel (ngrok, Cloudflare Tunnel)
In Claude.ai: go to Customize > Connectors → Add custom connector
Enter your server URL (e.g. https://your-domain.com/mcp/)
Claude supports authless or OAuth-based servers. For simplest setup, leave auth blank — the server will use the env vars you configured in step 1.

Note: Claude.ai does not support custom request headers. The server must be pre-configured with Meta credentials via environment variables. Each hosted server serves one WhatsApp Business Account.

location /mcp/ {
    proxy_pass http://127.0.0.1:8001/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

ChatGPT (remote — Responses API)

ChatGPT supports remote MCP servers via the Responses API. It supports both Streamable HTTP and SSE transports.

Option 1 — Server pre-configured with env vars (simplest):

from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

Option 2 — Per-request credentials via Bearer token:

Encode your Meta credentials as base64 JSON and pass them in the authorization field. OpenAI forwards this value as the Authorization header to your MCP server:

# Create the token
echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64
# Output: eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=

resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "authorization": "eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

Note: ChatGPT only supports remote MCP servers (no local stdio). Your server must be publicly accessible over HTTPS.

Cursor (stdio)

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

VS Code Copilot (stdio)

Add to .vscode/mcp.json:

{
  "servers": {
    "whatsapp": {
      "type": "stdio",
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

Per-Request Credentials (direct HTTP / curl / scripts)

For programmatic access or custom MCP clients, you can pass per-request credentials instead of relying on server env vars. Two methods are supported:

Method 1 — Bearer token (recommended):

Base64-encode a JSON object with your Meta credentials:

# Create the token
TOKEN=$(echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64)

# Use it
curl -H "Authorization: Bearer $TOKEN" https://your-server.com/mcp/ ...

Required fields: access_token, phone_number_id, waba_id. Optional: app_id, api_version.

Method 2 — X-Meta- headers:*

Header	Required	Description
`X-Meta-Access-Token`	Yes	Your Meta access token
`X-Meta-Phone-Number-Id`	Yes	Your WhatsApp phone number ID
`X-Meta-Business-Account-Id`	Yes	Your WhatsApp Business Account ID
`X-Meta-App-Id`	No	Your Meta app ID (for media uploads)
`X-Meta-Api-Version`	No	API version (defaults to v24.0)

If neither Bearer token nor X-Meta-* headers are present, the server falls back to environment variables.

Usage Examples

Once connected, just talk to your AI assistant:

"Create a marketing template called summer_sale with a header image, body text about 50% off, and a Shop Now button"

"List all my approved templates"

"Send the order_confirmation template to +919876543210 with order number ORD-456"

"Validate this template before I submit it: ..."

"Check the status of template ID 123456789"

Supported Template Types

Meta's API has 2 template categories(excluding Authentication). Within each category, templates can have different structural variants — each with its own component layout and validation rules.

Marketing Templates

Structural Variant	Create	Send	Key Components
Text / Image / Video / Document	✅	✅	Header (optional) + Body + Footer + Buttons
Carousel	✅	✅	Cards with per-card header, body, buttons
Catalog	✅	✅	Body + `CATALOG` button
Limited-Time Offer (LTO)	✅	✅	Body + `limited_time_offer` component + copy code button
Coupon Code	✅	✅	Body + `copy_code` button
Multi-Product Message (MPM)	✅	✅	Body + `product_list` action with sections
Single-Product Message (SPM)	✅	✅	Body + `product` action
Product Card Carousel	✅	✅	Body + product cards with buttons
Call Permission	✅	—	Body + `call_permission` button

Utility Templates

Structural Variant	Create	Send	Key Components
Text / Image / Video / Document	✅	✅	Header (optional) + Body + Footer + Buttons
Order Details	✅	✅	Body + `order_details` button with payment payload
Order Status	✅	✅	Body + order status parameters

How routing works: When you call create_template, the server inspects the components to auto-detect the structural variant (e.g., presence of cards[] → Carousel, CATALOG button → Catalog) and applies the correct validator. You just pass category: "MARKETING" or "UTILITY" — the variant is determined from the component structure.

Running Tests

pip install pytest pytest-asyncio
python -m pytest tests/ -v

Project Structure

whatsapp-mcp/
├── whatsapp_mcp/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # Entry point (python -m whatsapp_mcp)
│   ├── config.py            # Environment config loader
│   ├── meta_api.py          # Async Meta Graph API client
│   ├── middleware.py         # ASGI middleware for per-request credentials
│   ├── server.py            # MCP server with 8 tools
│   ├── models/              # Pydantic data models
│   │   ├── body.py          # Body component
│   │   ├── header.py        # Header component (text/image/video/document)
│   │   ├── footer.py        # Footer component
│   │   ├── buttons.py       # Button types (URL, phone, quick reply, etc.)
│   │   ├── buttons_component.py
│   │   ├── enums.py         # Template categories, types, formats
│   │   └── order_models.py  # Order-related models (checkout templates)
│   └── validators/
│       ├── create/          # 12 template creation validators
│       └── send/            # 11 template send validators
├── tests/
│   ├── test_validators.py   # Validator tests
│   ├── test_meta_api.py     # API client tests (mocked HTTP)
│   └── test_tools.py        # MCP tool registration & helper tests
├── .env.example
├── requirements.txt
├── LICENSE                  # MIT
└── ROADMAP.md

Requirements

Python 3.10+
Meta WhatsApp Business Account
System User access token with whatsapp_business_messaging and whatsapp_business_management permissions

Dependencies

Package	Purpose
`mcp`	Model Context Protocol SDK
`httpx`	Async HTTP client for Meta API
`pydantic`	Payload validation
`python-dotenv`	Environment config

Roadmap

See ROADMAP.md for planned features.

License

MIT — see LICENSE.

Built by Jina Connect — the WhatsApp Business CX platform.

WhatsApp Business MCP