io.github.nakulben/whatsapp-mcp

Official

by nakulben · Python

WhatsApp MCP Server

Manage WhatsApp Business templates and send messages via Meta Cloud API

Manage WhatsApp Business templates and send messages via Meta Cloud API.

Topics

claudemcpmeta-cloud-apiwhatsappwhatsapp-business-api

README.md12 KBView on GitHub

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

bash

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

bash

cp .env.example .env

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:

bash

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

Claude Desktop (stdio — local)

Add to claude_desktop_config.json:

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:

bash

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.

<details> <summary>Example nginx config</summary>

nginx

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

python

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:

bash

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

python

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:

json

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

VS Code Copilot (stdio)

Add to .vscode/mcp.json:

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:

bash

# 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

bash

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

Project Structure

code

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.

Install

Configuration

Environment variables

META_ACCESS_TOKENrequiredsecret

Meta API access token with whatsapp_business_messaging and whatsapp_business_management permissions

META_WABA_IDrequired

WhatsApp Business Account ID

META_PHONE_NUMBER_IDrequired

WhatsApp phone number ID

META_APP_ID

Meta app ID (for media uploads)

META_API_VERSION

Meta Graph API version (defaults to v24.0)

claude_desktop_config.json

{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "uvx",
      "args": [
        "jina-whatsapp-mcp"
      ],
      "env": {
        "META_ACCESS_TOKEN": "<YOUR_META_ACCESS_TOKEN>",
        "META_WABA_ID": "<YOUR_META_WABA_ID>",
        "META_PHONE_NUMBER_ID": "<YOUR_META_PHONE_NUMBER_ID>",
        "META_APP_ID": "<YOUR_META_APP_ID>",
        "META_API_VERSION": "<YOUR_META_API_VERSION>"
      }
    }
  }
}