Skip to main content
Glama
WhatsApp Business MCP

WhatsApp Business MCP

by nakulben

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.

Related MCP server: gaviwhatsapp-mcp

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.

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

    python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8001
  2. Put it behind HTTPS using nginx, Caddy, or a tunnel (ngrok, Cloudflare Tunnel)

  3. In Claude.ai: go to Customize > Connectors → Add custom connector

  4. Enter your server URL (e.g. https://your-domain.com/mcp/)

  5. 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.

Available Tools

8 tools
check_template_statusA

Check the approval status of a WhatsApp template.

Use this after creating a template to see if Meta approved or rejected it.

Args: template_name: Template name to check template_id: Meta template ID to check directly

Returns: JSON with current status (APPROVED, PENDING, REJECTED, etc.)

Inputs: template_name, template_id. Returns: result

create_templateA

Create and submit a WhatsApp template to Meta for approval.

The template will go through Meta's review process. Check status with check_template_status after submission.

Args: name: Template name (lowercase, underscores, starts with letter, max 512) category: MARKETING or UTILITY language: Language code (e.g. "en", "en_US", "hi") components: List of component dicts. Each has a "type" (HEADER, BODY, FOOTER, BUTTONS) and type-specific fields. Example: [ {"type": "HEADER", "format": "TEXT", "text": "Hello {{1}}", "example": {"header_text": ["John"]}}, {"type": "BODY", "text": "Your order {{1}} is {{2}}.", "example": {"body_text": [["ORD-123", "confirmed"]]}}, {"type": "FOOTER", "text": "Reply STOP to opt out"}, {"type": "BUTTONS", "buttons": [ {"type": "QUICK_REPLY", "text": "Track Order"}, {"type": "URL", "text": "View Details", "url": "https://example.com/order/{{1}}", "example": ["https://example.com/order/123"]} ]} ]

Returns: JSON with template ID and status on success, or error details.

Inputs: name (required), category (required), language (required), components (required). Returns: result

delete_templateA

Delete a WhatsApp template by name.

WARNING: This permanently deletes ALL language variants of the template.

Args: template_name: Name of the template to delete

Returns: JSON confirming deletion.

Inputs: template_name (required). Returns: result

get_template_detailA

Get full details of a WhatsApp template by name or ID.

Provide either template_name or template_id (not both).

Args: template_name: Template name to look up template_id: Meta template ID to look up directly

Returns: JSON with full template details including components.

Inputs: template_name, template_id. Returns: result

list_templatesA

List WhatsApp message templates.

Args: limit: Max templates to return (1-100, default 20) after: Pagination cursor for next page name: Filter by template name (exact match) status: Filter by status: APPROVED, PENDING, REJECTED, PAUSED, DISABLED category: Filter by category: MARKETING, UTILITY

Returns: JSON with list of templates and pagination info.

Inputs: limit, after, name, status, +1 more. Returns: result

send_bulk_template_messagesA

Send an approved template message to multiple phone numbers.

Messages are sent sequentially (one API call per recipient). Each result is tracked individually.

Args: to_list: List of phone numbers with country code template_name: Name of the approved template language: Language code (default "en") components: Optional parameter components (same for all recipients)

Returns: JSON with per-recipient results (successes and failures).

Inputs: to_list (required), template_name (required), language, components. Returns: result

send_template_messageA

Send an approved template message to a phone number.

Args: to: Recipient phone number with country code (e.g. "+919876543210") template_name: Name of the approved template to send language: Language code matching the template (default "en") components: Optional list of component parameter dicts for dynamic values. Example for a template with header image and body params: [ {"type": "header", "parameters": [ {"type": "image", "image": {"link": "https://example.com/img.jpg"}} ]}, {"type": "body", "parameters": [ {"type": "text", "text": "John"}, {"type": "text", "text": "ORD-123"} ]} ]

Returns: JSON with message ID on success.

Inputs: to (required), template_name (required), language, components. Returns: result

validate_templateA

Validate a WhatsApp template against Meta's rules before submitting.

Use this to check for errors before creating a template.

Args: name: Template name (lowercase, underscores, starts with letter) category: MARKETING or UTILITY language: Language code (e.g. "en", "en_US", "hi") components: List of component dicts (HEADER, BODY, FOOTER, BUTTONS) template_type: TEXT, IMAGE, VIDEO, DOCUMENT, CAROUSEL, CATALOG, etc. is_lto: True if this is a Limited Time Offer template

Returns: Validation result with any errors found.

Inputs: name (required), category (required), language (required), components (required), +2 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a distinct, well-defined purpose with clear boundaries. The single vs. bulk sending tools are clearly differentiated, as are validation (pre-submission check) vs. creation (actual submission). Status checking and detail retrieval serve different workflow needs despite both being read operations.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (create_template, send_template_message, check_template_status). Related operations use consistent core terms ('template', 'send') with appropriate qualifiers ('bulk', 'status', 'detail') to distinguish variants.

    Tool Count5/5

    Eight tools is well-scoped for WhatsApp Business template management, covering the full lifecycle (create, validate, list, get, delete, check status) and messaging (single and bulk send). No tools feel redundant or gratuitous.

    Completeness4/5

    Covers template CRUD operations comprehensively (note: WhatsApp templates cannot be updated, only deleted/recreated). Minor gap: no tools to check delivery/read status of sent messages after sending, only the initial send operations.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers