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.

Remote deployment (HTTP transport)

For unattended / scheduled use, the server can also run as an always-on HTTPS service and be added to Claude as a custom connector (Settings → Connectors → Add custom connector → give it the public URL). It exposes a Streamable HTTP endpoint at /mcp.

Security: the HTTP endpoint requires the secret token. A public send endpoint must be authenticated, otherwise anyone who finds the URL could send WhatsApp messages on your account. The server refuses to start over HTTP without MCP_AUTH_TOKEN set. It accepts the token two ways:

• Header (preferred): POST /mcp with Authorization: Bearer <MCP_AUTH_TOKEN>. Use this whenever your client can set headers (e.g. Claude Code's --header). The token never appears in the URL.
• Path (fallback): POST /mcp/<MCP_AUTH_TOKEN>. For connector UIs that only accept a URL and cannot attach a header. The URL then is the secret, treat it accordingly (see SECURITY.md): use the long hex token, do not share or screenshot the URL, and be aware the host's access logs may record the path.

Extra env vars for HTTP mode:

Variable	Required	Description
MCP_TRANSPORT	Yes (http)	Set to http to run the HTTP server (default stdio).
MCP_AUTH_TOKEN	Yes	Long random secret. Callers must present it as a bearer token. Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
PORT	No	Port to listen on. Hosts like Render set this automatically.

Endpoints:

• POST /mcp — the MCP endpoint (bearer auth required).
• GET /health — unauthenticated health check, also useful for a keepalive ping to stop a free host from sleeping.

Keepalive (no external pinger needed). On a free host that sleeps when idle, the server can keep itself awake by self-pinging /health on a timer. On Render this turns on automatically (it reads RENDER_EXTERNAL_URL). Elsewhere, set KEEPALIVE_URL to your public base URL. Tune the interval with KEEPALIVE_MINUTES (default 10; the host sleeps after ~15 min idle). Note a single always-on free Render service uses roughly 730 of the 750 free monthly hours.

Deploy to Render

A render.yaml blueprint is included. Push this repo to GitHub, then in Render: New → Blueprint and point it at the repo. Set the secrets (MCP_AUTH_TOKEN, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_DEFAULT_RECIPIENT) in the Render dashboard, never in the file. Render health-checks /health; a separate keepalive ping to /health keeps a free instance awake.

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