Skip to main content
Glama
whatsapp-business-mcp

whatsapp-business-mcp

by Gonzalez8

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

wa_get_business_accounts

yes

Discovery — start here. List WABAs owned by a Meta Business.

wa_get_phone_numbers

yes

List phone numbers on a WABA (returns phone_number_id for sending).

wa_get_templates

yes

List templates with filters (status, language, name) and pagination.

wa_create_template

no

Create a new message template (goes through Meta review).

wa_delete_template

destructive

Delete a template by name (all languages).

wa_send_template

no

Send an approved template message. Validates phone (E.164), template name, locale.

wa_get_message_status

yes

Look up a message by wamid.

wa_api_call

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

WHATSAPP_TOKEN

yes

—

Meta Graph API access token (system user token recommended).

WHATSAPP_API_VERSION

no

v23.0

Graph API version.

MCP_TRANSPORT

no

stdio

stdio or http.

PORT

no

3000

HTTP transport port.

HOST

no

0.0.0.0

HTTP transport bind address.

MCP_HTTP_PATH

no

/mcp

HTTP transport endpoint path.

MCP_BEARER_TOKEN

no

—

If set, HTTP requests must send Authorization: Bearer <token>.

Install

npm install
npm test

Run locally (stdio)

WHATSAPP_TOKEN=... npm start

Run 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 /health

Configure 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-mcp

Deployment

Railway

  1. New project → Deploy from GitHub.

  2. Railway detects the Dockerfile. Set service variables:

    • WHATSAPP_TOKEN

    • MCP_BEARER_TOKEN (shared secret for the HTTP endpoint)

  3. PORT is provided automatically by Railway; the server respects it.

  4. Public URL → https://<service>.up.railway.app/mcp.

Fly.io

fly launch --no-deploy
fly secrets set WHATSAPP_TOKEN=... MCP_BEARER_TOKEN=...
fly deploy

Ensure the [http_service] block in fly.toml uses internal_port = 3000.

Render

  1. New → Web Service → connect repo. Render detects the Dockerfile.

  2. Add environment variables WHATSAPP_TOKEN and MCP_BEARER_TOKEN.

  3. Health check path: /health.

Security notes

  • Always set MCP_BEARER_TOKEN when 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_call is 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 match xx or xx_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 tools
wa_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_apps

  • query_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:

  1. wa_get_business_accounts (this tool) → pick a waba_id

  2. wa_get_phone_numbers(waba_id) → pick a phone_number_id for sending

  3. wa_get_templates(waba_id) → pick an APPROVED template

  4. 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_id is the numeric ID of YOUR sending number (from wa_get_phone_numbers), NOT the destination phone.

  • to must be E.164 (digits only, country code first), e.g. 351912345678.

  • components_json is 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

    A4.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers