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

Related MCP server: bach-whatsapp_number_validators

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

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.