nakulben/whatsapp-mcp
time offer, and flows) from any MCP client.
Ask AI about nakulben/whatsapp-mcp
Powered by Claude Β· Grounded in docs
I know everything about nakulben/whatsapp-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
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;
}
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_salewith a header image, body text about 50% off, and a Shop Now button"
"List all my approved templates"
"Send the
order_confirmationtemplate 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 ofcards[]β Carousel,CATALOGbutton β Catalog) and applies the correct validator. You just passcategory: "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_messagingandwhatsapp_business_managementpermissions
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.
