whatsapp-business-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@whatsapp-business-mcp Send welcome template to +1234567890"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WhatsApp Business MCP Server
MCP server for the WhatsApp Business / Meta Graph API. List business accounts and phone numbers, manage message templates, send template messages, and look up message status.
Supports two transports:
stdio — default; for local Claude Desktop / Claude Code / Cursor.
HTTP (Streamable / SSE) — for remote deployment (Railway, Fly.io, Render, your own container).
Tools
Tool | Read-only | Description |
| yes | Discovery — start here. List WABAs owned by a Meta Business. |
| yes | List phone numbers on a WABA (returns |
| yes | List templates with filters (status, language, name) and pagination. |
| no | Create a new message template (goes through Meta review). |
| destructive | Delete a template by name (all languages). |
| no | Send an approved template message. Validates phone (E.164), template name, locale. |
| yes | Look up a message by |
| restricted | Escape hatch — only whitelisted WhatsApp Business paths. |
Related MCP server: lingtai-whatsapp
Resources
The server also exposes the same inventory as MCP resources so the host can cache them:
whatsapp://business-accounts/{business_id}whatsapp://phone-numbers/{waba_id}whatsapp://templates/{waba_id}
Environment variables
Variable | Required | Default | Description |
| yes | — | Meta Graph API access token (system user token recommended). |
| no |
| Graph API version. |
| no |
|
|
| no |
| HTTP transport port. |
| no |
| HTTP transport bind address. |
| no |
| HTTP transport endpoint path. |
| no | — | If set, HTTP requests must send |
Install
npm install
npm testRun locally (stdio)
WHATSAPP_TOKEN=... npm startRun as an HTTP server
WHATSAPP_TOKEN=... MCP_BEARER_TOKEN=... npm run start:http
# → MCP listening on http://0.0.0.0:3000/mcp
# → Health check at GET /healthConfigure in Claude Code / Desktop (stdio)
Once published to npm:
{
"mcpServers": {
"whatsapp-business": {
"command": "npx",
"args": ["-y", "whatsapp-business-mcp-server"],
"env": { "WHATSAPP_TOKEN": "your-token-here" }
}
}
}Or from a local checkout:
{
"mcpServers": {
"whatsapp-business": {
"command": "node",
"args": ["/absolute/path/to/whatsapp-business-mcp/src/server.mjs"],
"env": { "WHATSAPP_TOKEN": "your-token-here" }
}
}
}Configure as a remote HTTP MCP
{
"mcpServers": {
"whatsapp-business": {
"url": "https://your-host.example.com/mcp",
"headers": { "Authorization": "Bearer your-bearer-token" }
}
}
}Docker
docker build -t whatsapp-business-mcp .
docker run --rm -p 3000:3000 \
-e WHATSAPP_TOKEN=... \
-e MCP_BEARER_TOKEN=... \
whatsapp-business-mcpDeployment
Railway
New project → Deploy from GitHub.
Railway detects the Dockerfile. Set service variables:
WHATSAPP_TOKENMCP_BEARER_TOKEN(shared secret for the HTTP endpoint)
PORTis provided automatically by Railway; the server respects it.Public URL →
https://<service>.up.railway.app/mcp.
Fly.io
fly launch --no-deploy
fly secrets set WHATSAPP_TOKEN=... MCP_BEARER_TOKEN=...
fly deployEnsure the [http_service] block in fly.toml uses internal_port = 3000.
Render
New → Web Service → connect repo. Render detects the Dockerfile.
Add environment variables
WHATSAPP_TOKENandMCP_BEARER_TOKEN.Health check path:
/health.
Security notes
Always set
MCP_BEARER_TOKENwhen exposing the HTTP transport publicly. Without it, anyone who reaches the endpoint can use your WhatsApp Business token.The token is read from the server's environment, never accepted from MCP clients.
wa_api_callis restricted to a whitelist of WhatsApp Business paths; arbitrary Graph endpoints are rejected.Inputs are validated before requests reach Meta: phone numbers must be E.164, template names match
[a-z0-9_]+, locales matchxxorxx_YY.
Error handling
The server classifies Graph API failures and returns structured hints to the LLM:
token_expired/token_invalid(HTTP 401, code 190) — refresh credentials.permission_denied(HTTP 403, code 10/200) — scopes/asset access missing.rate_limited(HTTP 429, code 4) — back off and retry.not_found(HTTP 404).upstream_error(5xx).network_error— fetch failed before reaching Meta.
Available Tools
8 toolswa_api_callA
Escape hatch for WhatsApp Business / Meta Graph endpoints that don't have a dedicated tool yet.
Restricted: only paths matching a curated allowlist of WhatsApp Business resources are accepted (message_templates, phone_numbers, messages, media, business_profile, analytics, subscribed_apps, owned_whatsapp_business_accounts, single-ID reads, wamid lookups). Anything else is rejected.
Prefer the typed tools when one matches — they validate inputs and surface clearer errors.
Inputs:
path: starts with/, e.g./{waba_id}/subscribed_appsquery_params: raw query string without leading?(will be appended)body_json: JSON string of the request body, used with POST/DELETE
Inputs: path (required), method (required), body_json, query_params.
wa_create_templateA
Create a new message template in a WABA. Templates go through Meta review before they can be sent.
When to use: setting up a new outbound notification, marketing or authentication message type.
Inputs:
name: lowercase letters, digits, underscores only.language: locale code matching Meta's list (en, pt_PT, es_ES, ...).category: UTILITY | MARKETING | AUTHENTICATION. Affects pricing and review rules.components_json: JSON array following Meta's component schema. Common types: [{"type":"HEADER","format":"TEXT","text":"Hello"}, {"type":"BODY","text":"Hi {{1}}, your code is {{2}}.","example":{"body_text":[["Alice","123"]]}}, {"type":"FOOTER","text":"Reply STOP to opt out"}]
Returns: the new template's ID. Status starts as PENDING; poll wa_get_templates for review result.
Inputs: name (required), waba_id (required), category (required), language (required), +1 more.
wa_delete_templateA
Delete a message template from a WABA by name. WARNING: deletes ALL languages of that template.
When to use: removing obsolete or rejected templates. Cannot be undone.
Note: deletion is irreversible. Confirm with the user before invoking.
Inputs: name (required), waba_id (required).
wa_get_business_accountsA
DISCOVERY — START HERE.
List all WhatsApp Business Accounts (WABAs) owned by a Meta Business. This is the entry
point for almost every other tool: most calls take a waba_id returned here.
Typical flow:
wa_get_business_accounts (this tool) → pick a
waba_idwa_get_phone_numbers(waba_id) → pick a
phone_number_idfor sendingwa_get_templates(waba_id) → pick an APPROVED template
wa_send_template(phone_number_id, to, template_name, language_code, ...)
Resources whatsapp://business-accounts/{business_id} provide the same data and can be
cached by the host.
Inputs: business_id (required), fields.
wa_get_message_statusA
Look up information about a previously sent WhatsApp message by its ID.
Use this after wa_send_template to confirm Graph API received the message. Note that WhatsApp delivery/read status (sent → delivered → read) is pushed asynchronously via webhooks; the Graph API does not expose a polling endpoint for those transitions. This tool retrieves the message resource directly and surfaces whatever Meta returns.
Inputs: the wamid returned by wa_send_template.
Inputs: message_id (required), fields.
wa_get_phone_numbersA
List phone numbers registered to a WhatsApp Business Account (WABA).
Use this to discover the phone_number_id required by wa_send_template. display_phone_number
is the human-readable number (e.g. +351 91 234 5678); id is the numeric resource ID you pass
as phone_number_id to send.
Also returns quality_rating (GREEN/YELLOW/RED) and messaging status, useful for diagnosing delivery problems.
Inputs: waba_id (required), fields.
wa_get_templatesA
List message templates for a WhatsApp Business Account (WABA), with optional filters.
When to use: discovery before sending (wa_send_template requires an APPROVED template), auditing template inventory, or verifying review status after wa_create_template.
Filters are applied server-side (status, name) or client-side (language). Use pagination
via after when has_more is true in the response.
Returns: { count, templates[], has_more, next_cursor? } where each template includes name, language, status, category and component definitions.
Inputs: waba_id (required), name, after, limit, +2 more.
wa_send_templateA
Send a pre-approved template message to a recipient on WhatsApp.
When to use: outbound notifications, marketing or utility messages where the recipient is outside the 24-hour customer service window, or any first-contact message.
Requirements:
The template must already exist and be in APPROVED status (use wa_get_templates to verify).
phone_number_idis the numeric ID of YOUR sending number (from wa_get_phone_numbers), NOT the destination phone.tomust be E.164 (digits only, country code first), e.g. 351912345678.components_jsonis required when the template has variables ({{1}}, header media, buttons).
Returns: the WhatsApp message ID (wamid) on success, which can be used with wa_get_message_status.
Limitations: templates with header media require uploaded media handles; delivery/read status is delivered asynchronously via webhooks — this tool returns only the accepted message ID.
Inputs: to (required), language_code (required), template_name (required), phone_number_id (required), +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and action: discovery (business accounts, phone numbers, templates), mutation (create/delete/send), and status lookup. No two tools overlap in purpose; wa_api_call is clearly an escape hatch for uncovered endpoints.
All tool names follow a consistent 'wa_verb_noun' pattern (e.g., wa_get_templates, wa_create_template, wa_send_template). The only outlier, wa_api_call, still fits the verb_noun style with 'call' as the verb. Naming is uniform and predictable.
8 tools is a well-scoped number for a WhatsApp Business server. Each tool earns its place in the primary workflow—discovery, template management, sending, and status checking—without unnecessary bloat or obvious missing essentials.
The server covers the core lifecycle: discover accounts/numbers/templates, create/delete templates, send messages, and check message status. Missing an update-template operation, but the wa_api_call escape hatch provides a workaround, so the gap is minor.
Maintenance
Related MCP Connectors
WhatsApp (Web + Business API), SMS, contacts, and call records via 2Chat's MCP server.
Unified messaging MCP server: WhatsApp, Instagram, Telegram, SMS, Messenger & email support inbox
WhatsApp Business on Meta's Cloud API: team inbox, templates, AI support agents and analytics.
WhatsMCP connects Claude and other MCP-compatible AI agents directly to WhatsApp. Send and receive text, images, documents, and voice notes; manage groups (create, add/remove members, promote admins); look up contacts and profiles; follow channels; and read call and message history — all through a standard MCP interface. For voice use cases, WhatsMCP offers SIP-based calling plans (inbound-only, or full inbound/outbound) so AI voice agents can answer and place WhatsApp calls, plus low-latency WebSocket integrations with voice agent providers like ElevenLabs. Multiple WhatsApp accounts can be paired and managed per workspace, with webhook support for real-time inbound message delivery to your own infrastructure.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP (Multi-Agent Conversation Protocol) Server that enables interaction with the WhatsApp Business API, allowing agents to send messages, manage media, and perform other WhatsApp business operations through natural language.1-

lingtai-whatsappofficial
AlicenseNot gradedqualityFmaintenanceMCP server for interacting with the official Meta WhatsApp Business Platform/Cloud API, enabling sending messages, managing contacts, templates, and handling webhook callbacks.Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables sending messages, managing templates, uploading media, and configuring webhooks for WhatsApp Business via the MCP protocol.34 npm5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for WATI WhatsApp Business API enabling AI assistants to send messages, manage contacts, and handle media.MIT