whatsapp-send-mcp

A least-privilege, send-only Model Context Protocol server for WhatsApp.

It exposes two send tools and nothing else, backed by Meta's official WhatsApp Cloud API:

• send_whatsapp_message — send a free-form text message (deliverable only inside WhatsApp's 24-hour customer service window).
• send_whatsapp_template — send a pre-approved template message (deliverable at any time, the reliable path for scheduled notifications).

That is the entire surface area:

• It can send a text or template message to a specified or default recipient.
• It cannot read messages, list chats, access contacts, read statuses, or download/upload media. None of that is implemented, and the Graph API token scope it uses (whatsapp_business_messaging) does not grant a "read messages" capability in the first place. Send-only is enforced by the platform, not just by this wrapper.

Why the official Cloud API (and not Baileys / whatsapp-web.js)

• Official and Terms-of-Service compliant.
• Does not require linking your personal WhatsApp account as a device.
• The API has no endpoint to read a user's message history, so a send-only integration is enforced at the platform level.

What it does not do (by design)

• No inbound message handling or webhooks.
• No reading of message history, chats, contacts, or statuses.
• No media upload or download.
• No group messaging.
• No template management from the server (creating/editing/deleting templates). Templates are created once in WhatsApp Manager, or via the included one-off create:template script; the server only sends already-approved templates.

These are deliberate non-goals. Adding a read capability later would be a separate, deliberate decision, not something bundled into this package.

Requirements

• Node.js 20 or newer.
• A WhatsApp Cloud API app on Meta for Developers, with an access token and a phone number ID.

Install

Run directly with npx (no install needed):

npx @praise25/whatsapp-mcp-server

Or install globally:

npm install -g @praise25/whatsapp-mcp-server

Configuration

All configuration is via environment variables. Nothing is hardcoded, and the access token is never logged.

| Variable | Required | Description | | --- | --- | --- | | WHATSAPP_ACCESS_TOKEN | Yes | Meta system-user or temporary access token, scoped to whatsapp_business_messaging. | | WHATSAPP_PHONE_NUMBER_ID | Yes | The Cloud API phone number ID (a numeric ID, not the phone number itself). | | WHATSAPP_DEFAULT_RECIPIENT | No | Default recipient in E.164 format (e.g. +2348012345678), used when to is omitted. | | WHATSAPP_GRAPH_API_VERSION | No | Graph API version segment. Defaults to v21.0. |

The server validates required variables at startup and fails fast with a clear error if any are missing. See .env.example.

How to get a WhatsApp Cloud API test number and access token

1. Go to Meta for Developers and create (or open) an app of type Business.
2. Add the WhatsApp product to the app.
3. Open WhatsApp > API Setup. Meta provides a free test phone number for development.
4. Copy the Phone number ID shown there into WHATSAPP_PHONE_NUMBER_ID.
5. Copy the temporary access token into WHATSAPP_ACCESS_TOKEN. (Temporary tokens last ~24 hours. For a longer-lived token, create a System User in Meta Business Settings and grant it the whatsapp_business_messaging permission only.)
6. Still on the API Setup page, add your own phone number to the allowed recipient list so the test number is permitted to message you.
7. Messages sent from a test number can only go to numbers on that allowed list until the number is fully verified for production.

The one tool: send_whatsapp_message

Input:

| Field | Type | Required | Description | | --- | --- | --- | --- | | to | string | Optional if WHATSAPP_DEFAULT_RECIPIENT is set | Recipient in E.164 format, e.g. +2348012345678. | | message | string | Yes | The text body to send. |

Output:

• On success: the WhatsApp message ID.
• On failure: a distinguishable, human-readable error (authentication, invalid recipient, rate limit, server error, network error), not a generic "failed".

Behavior notes:

• Calls POST https://graph.facebook.com/v21.0/{PHONE_NUMBER_ID}/messages with a type: "text" payload.
• Retries at most once, and only on a 5xx or network error. It never retries on a 4xx (those are permanent: bad token, bad number, etc.).

The 24-hour window. A free-form text message is only delivered if the recipient has messaged your number within the last 24 hours. Outside that window the API still returns success, but WhatsApp drops delivery. For reliable, unprompted delivery, use a template (below).

The other tool: send_whatsapp_template

Sends a pre-approved template, which WhatsApp delivers at any time, with no 24-hour-window dependency. This is the reliable choice for scheduled notifications, alerts, and digests.

Input:

| Field | Type | Required | Description | | --- | --- | --- | --- | | to | string | Optional if WHATSAPP_DEFAULT_RECIPIENT is set | Recipient in E.164 format. | | templateName | string | Yes | An approved template name (the built-in hello_world always exists). | | languageCode | string | No | BCP-47 code the template was approved in. Defaults to en_US. | | headerParams | string[] | No | Ordered values for the header's {{1}}, {{2}}, … placeholders. | | bodyParams | string[] | No | Ordered values for the body's {{1}}, {{2}}, … placeholders. Each value must be a single line (no newlines/tabs, WhatsApp rejects them inside a variable). |

The server stores none of the template wording. Meta owns the approved template; the caller supplies only the variable values that fill its blanks.

Registering a template

Templates are created once in WhatsApp Manager (Create template), or reproducibly via the included one-off script:

npm run create:template

This posts a template to your WABA and requires the token to also have the whatsapp_business_management permission (sending only needs messaging). After submission, wait for the status to become APPROVED before sending it. Note WhatsApp's variable-to-text ratio rule: a body with too many variables relative to its fixed wording is rejected, add more fixed text or fewer variables.

Use with an MCP client

Claude Desktop / Claude Code

Add to your MCP client configuration (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "whatsapp-send": {
      "command": "npx",
      "args": ["-y", "@praise25/whatsapp-mcp-server"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "your-access-token",
        "WHATSAPP_PHONE_NUMBER_ID": "1234567890",
        "WHATSAPP_DEFAULT_RECIPIENT": "+2348012345678"
      }
    }
  }
}

The server communicates over stdio.

Local development

npm install
npm run build      # compile TypeScript to dist/
npm test           # run unit tests (fetch is mocked; no real API calls)

Manual send tests

To verify against the real Graph API before publishing, put your credentials in a local .env (copy from .env.example) and run any of these. They actually deliver messages, so use a number you control.

npm run test:send                      # free-form text to WHATSAPP_DEFAULT_RECIPIENT
npm run test:send -- +2348012345678    # text to an explicit recipient

npm run test:template                  # built-in hello_world template (works anytime)

npm run create:template                # one-off: register the example topic_digest_report template
npm run test:digest                    # send that template once approved
npm run test:digest -- "AI News" "Morning" "OpenAI shipped X • DeepMind announced Y"

test:template and test:digest demonstrate template delivery, which works regardless of the 24-hour window.

Security

See SECURITY.md. In short: the access token is read only from an environment variable, is never committed and never logged, and revoking it in the Meta dashboard immediately disables this integration entirely.

License

MIT