WhatsApp MCP Server

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

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:

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.

1. Host the server with env vars configured, behind HTTPS:

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

1. Put it behind HTTPS using nginx, Caddy, or a tunnel (ngrok, Cloudflare Tunnel)
2. In Claude.ai: go to Customize > Connectors → Add custom connector
3. Enter your server URL (e.g. https://your-domain.com/mcp/)
4. 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.

Example nginx config

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; }

</details>

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:**

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

Utility Templates

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

Roadmap

See ROADMAP.md for planned features.

License

MIT — see LICENSE.

---

Built by Jina Connect — the WhatsApp Business CX platform.