{ "markdown": "# WhatsApp MCP Server\n\n\n\nManage WhatsApp Business templates and send messages from **Claude, ChatGPT, Cursor, VS Code Copilot**, or any MCP-compatible client — powered by the Meta Cloud API.\n\n

\n \"MCP\n \"Meta\n \"MIT\n \"Python\n

\n\n## What It Does\n\n| Tool | Description |\n|------|-------------|\n| `validate_template` | Validate a template payload before submitting to Meta |\n| `create_template` | Submit a template for Meta approval |\n| `list_templates` | List templates with optional filters (status, category, name) |\n| `get_template_detail` | Get full details of a template by ID |\n| `check_template_status` | Quick status check for a template |\n| `delete_template` | Delete a template by name |\n| `send_template_message` | Send an approved template to a phone number |\n| `send_bulk_template_messages` | Send an approved template to multiple phone numbers |\n\n**8 tools** covering the full template lifecycle: create → validate → approve → send.\n\n## Quick Start\n\n### 1. Clone & Install\n\n```bash\ngit clone https://github.com/nakulben/whatsapp-mcp.git\ncd whatsapp-mcp\npython -m venv venv\nsource venv/bin/activate # Windows: venv\\Scripts\\activate\npip install -r requirements.txt\n```\n\n### 2. Configure Credentials\n\n```bash\ncp .env.example .env\n```\n\n```env\nMETA_ACCESS_TOKEN=your_access_token\nMETA_WABA_ID=your_whatsapp_business_account_id\nMETA_PHONE_NUMBER_ID=your_phone_number_id\nMETA_APP_ID=your_app_id # Optional, for media uploads\nMETA_API_VERSION=v24.0 # Optional, defaults to v24.0\n```\n\nEnvironment variables are used by **all modes** — local stdio and hosted remote.\n\n> **How to get these?** Go to [Meta for Developers](https://developers.facebook.com/), create or select your app, navigate to WhatsApp > API Setup.\n\n### 3. Connect to Your MCP Client\n\nThe server supports **3 transport modes**:\n\n| Transport | Command | Used By |\n|---|---|---|\n| `stdio` (default) | `python -m whatsapp_mcp` | Claude Desktop, Cursor, VS Code, Windsurf |\n| `sse` | `python -m whatsapp_mcp --transport sse` | Legacy remote clients |\n| `streamable-http` | `python -m whatsapp_mcp --transport streamable-http` | Claude.ai, ChatGPT, newer MCP clients |\n\nFor HTTP transports, you can customize host/port:\n```bash\npython -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8000\n```\n\n---\n\n#### Claude Desktop (stdio — local)\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"whatsapp\": {\n \"command\": \"/path/to/whatsapp-mcp/venv/bin/python\",\n \"args\": [\"-m\", \"whatsapp_mcp\"],\n \"env\": {\n \"META_ACCESS_TOKEN\": \"your_access_token\",\n \"META_WABA_ID\": \"your_waba_id\",\n \"META_PHONE_NUMBER_ID\": \"your_phone_number_id\",\n \"META_APP_ID\": \"your_app_id\"\n }\n }\n }\n}\n```\n\n#### Claude.ai Web (remote — streamable-http)\n\nClaude.ai connects to remote MCP servers as [custom connectors](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp). The connection originates from Anthropic's cloud servers, not from your machine.\n\n1. Host the server with env vars configured, behind HTTPS:\n ```bash\n python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8001\n ```\n2. Put it behind HTTPS using nginx, Caddy, or a tunnel (ngrok, Cloudflare Tunnel)\n3. In Claude.ai: go to [Customize > Connectors](https://claude.ai/customize/connectors) → Add custom connector\n4. Enter your server URL (e.g. `https://your-domain.com/mcp/`)\n5. 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.\n\n> **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.\n\n
\nExample nginx config\n\n```nginx\nlocation /mcp/ {\n proxy_pass http://127.0.0.1:8001/;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_read_timeout 86400;\n}\n```\n
\n\n#### ChatGPT (remote — Responses API)\n\nChatGPT supports remote MCP servers via the [Responses API](https://developers.openai.com/api/docs/guides/tools-connectors-mcp). It supports both Streamable HTTP and SSE transports.\n\n**Option 1 — Server pre-configured with env vars (simplest):**\n\n```python\nfrom openai import OpenAI\nclient = OpenAI()\nresp = client.responses.create(\n model=\"gpt-4.1\",\n tools=[{\n \"type\": \"mcp\",\n \"server_label\": \"whatsapp\",\n \"server_url\": \"https://your-domain.com/mcp/\",\n \"require_approval\": \"never\",\n }],\n input=\"List all my approved templates\",\n)\n```\n\n**Option 2 — Per-request credentials via Bearer token:**\n\nEncode your Meta credentials as base64 JSON and pass them in the `authorization` field.\nOpenAI forwards this value as the `Authorization` header to your MCP server:\n\n```bash\n# Create the token\necho -n '{\"access_token\":\"EAA...\",\"phone_number_id\":\"123\",\"waba_id\":\"456\"}' | base64\n# Output: eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=\n```\n\n```python\nresp = client.responses.create(\n model=\"gpt-4.1\",\n tools=[{\n \"type\": \"mcp\",\n \"server_label\": \"whatsapp\",\n \"server_url\": \"https://your-domain.com/mcp/\",\n \"authorization\": \"eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=\",\n \"require_approval\": \"never\",\n }],\n input=\"List all my approved templates\",\n)\n```\n\n> **Note:** ChatGPT only supports remote MCP servers (no local stdio). Your server must be publicly accessible over HTTPS.\n\n#### Cursor (stdio)\n\nAdd to `.cursor/mcp.json` in your project:\n\n```json\n{\n \"mcpServers\": {\n \"whatsapp\": {\n \"command\": \"/path/to/whatsapp-mcp/venv/bin/python\",\n \"args\": [\"-m\", \"whatsapp_mcp\"]\n }\n }\n}\n```\n\n#### VS Code Copilot (stdio)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"whatsapp\": {\n \"type\": \"stdio\",\n \"command\": \"/path/to/whatsapp-mcp/venv/bin/python\",\n \"args\": [\"-m\", \"whatsapp_mcp\"]\n }\n }\n}\n```\n\n#### Per-Request Credentials (direct HTTP / curl / scripts)\n\nFor programmatic access or custom MCP clients, you can pass per-request credentials instead of relying on server env vars. Two methods are supported:\n\n**Method 1 — Bearer token (recommended):**\n\nBase64-encode a JSON object with your Meta credentials:\n\n```bash\n# Create the token\nTOKEN=$(echo -n '{\"access_token\":\"EAA...\",\"phone_number_id\":\"123\",\"waba_id\":\"456\"}' | base64)\n\n# Use it\ncurl -H \"Authorization: Bearer $TOKEN\" https://your-server.com/mcp/ ...\n```\n\nRequired fields: `access_token`, `phone_number_id`, `waba_id`. Optional: `app_id`, `api_version`.\n\n**Method 2 — X-Meta-* headers:**\n\n| Header | Required | Description |\n|---|---|---|\n| `X-Meta-Access-Token` | Yes | Your Meta access token |\n| `X-Meta-Phone-Number-Id` | Yes | Your WhatsApp phone number ID |\n| `X-Meta-Business-Account-Id` | Yes | Your WhatsApp Business Account ID |\n| `X-Meta-App-Id` | No | Your Meta app ID (for media uploads) |\n| `X-Meta-Api-Version` | No | API version (defaults to v24.0) |\n\nIf neither Bearer token nor X-Meta-* headers are present, the server falls back to environment variables.\n\n## Usage Examples\n\nOnce connected, just talk to your AI assistant:\n\n> \"Create a marketing template called `summer_sale` with a header image, body text about 50% off, and a Shop Now button\"\n\n> \"List all my approved templates\"\n\n> \"Send the `order_confirmation` template to +919876543210 with order number ORD-456\"\n\n> \"Validate this template before I submit it: ...\"\n\n> \"Check the status of template ID 123456789\"\n\n## Supported Template Types\n\nMeta'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.\n\n### Marketing Templates\n\n| Structural Variant | Create | Send | Key Components |\n|---|---|---|---|\n| Text / Image / Video / Document | ✅ | ✅ | Header (optional) + Body + Footer + Buttons |\n| Carousel | ✅ | ✅ | Cards with per-card header, body, buttons |\n| Catalog | ✅ | ✅ | Body + `CATALOG` button |\n| Limited-Time Offer (LTO) | ✅ | ✅ | Body + `limited_time_offer` component + copy code button |\n| Coupon Code | ✅ | ✅ | Body + `copy_code` button |\n| Multi-Product Message (MPM) | ✅ | ✅ | Body + `product_list` action with sections |\n| Single-Product Message (SPM) | ✅ | ✅ | Body + `product` action |\n| Product Card Carousel | ✅ | ✅ | Body + product cards with buttons |\n| Call Permission | ✅ | — | Body + `call_permission` button |\n\n### Utility Templates\n\n| Structural Variant | Create | Send | Key Components |\n|---|---|---|---|\n| Text / Image / Video / Document | ✅ | ✅ | Header (optional) + Body + Footer + Buttons |\n| Order Details | ✅ | ✅ | Body + `order_details` button with payment payload |\n| Order Status | ✅ | ✅ | Body + order status parameters |\n\n> **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.\n\n## Running Tests\n\n```bash\npip install pytest pytest-asyncio\npython -m pytest tests/ -v\n```\n\n## Project Structure\n\n```\nwhatsapp-mcp/\n├── whatsapp_mcp/\n│ ├── __init__.py # Package version\n│ ├── __main__.py # Entry point (python -m whatsapp_mcp)\n│ ├── config.py # Environment config loader\n│ ├── meta_api.py # Async Meta Graph API client\n│ ├── middleware.py # ASGI middleware for per-request credentials\n│ ├── server.py # MCP server with 8 tools\n│ ├── models/ # Pydantic data models\n│ │ ├── body.py # Body component\n│ │ ├── header.py # Header component (text/image/video/document)\n│ │ ├── footer.py # Footer component\n│ │ ├── buttons.py # Button types (URL, phone, quick reply, etc.)\n│ │ ├── buttons_component.py\n│ │ ├── enums.py # Template categories, types, formats\n│ │ └── order_models.py # Order-related models (checkout templates)\n│ └── validators/\n│ ├── create/ # 12 template creation validators\n│ └── send/ # 11 template send validators\n├── tests/\n│ ├── test_validators.py # Validator tests\n│ ├── test_meta_api.py # API client tests (mocked HTTP)\n│ └── test_tools.py # MCP tool registration & helper tests\n├── .env.example\n├── requirements.txt\n├── LICENSE # MIT\n└── ROADMAP.md\n```\n\n## Requirements\n\n- Python 3.10+\n- Meta WhatsApp Business Account\n- System User access token with `whatsapp_business_messaging` and `whatsapp_business_management` permissions\n\n### Dependencies\n\n| Package | Purpose |\n|---------|---------|\n| `mcp` | Model Context Protocol SDK |\n| `httpx` | Async HTTP client for Meta API |\n| `pydantic` | Payload validation |\n| `python-dotenv` | Environment config |\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md) for planned features.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\nBuilt by [Jina Connect](https://jinaconnect.jinacode.systems/) — the WhatsApp Business CX platform.\n", "bytes": 11804, "sha": "e3a1eaee68675a0923a5c9bbc2a7619b6bf300012b45628e5746dddb2b5cec50", "repo_slug": "nakulben/whatsapp-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_nakulben_whatsapp_mcp_0996edf4/readme" }