WhatsApp Business Cloud API MCP (was-whatsapp-cloud-mcp)

A self-contained, cross-platform Model Context Protocol (MCP) server for the official WhatsApp Business Cloud API (Meta Graph API). Exposes 7 tools allowing AI coding assistants (Claude Desktop, Cursor, Antigravity, VS Code, Zed, etc.) to send text messages, media files, pre-approved marketing/utility templates, interactive quick-reply buttons, inspect phone quality ratings, and execute arbitrary calls to the WhatsApp Cloud API. Built by Web Analytics Solution.

Prerequisites

Related MCP server: whatsapp-mcp-server

Quick Start — 3 Steps

Step 1 — Get WhatsApp Cloud API Credentials

1. Go to developers.facebook.com/apps and select or create an App with the WhatsApp product.

2. In the left navigation, click WhatsApp > API Setup.

3. Copy your Phone Number ID (e.g. 1056...).

4. Generate an Access Token with the whatsapp_business_messaging and whatsapp_business_management permissions (or use a System User Token from Meta Business Settings).

5. (Optional) Copy your WhatsApp Business Account ID (WABA ID) for template management.

Step 2 — Connect

Run the interactive setup command in your terminal:

npx -y github:mnsmasum62786/was-whatsapp-cloud-mcp auth

1. Paste your Meta Access Token when prompted.

2. Paste your Phone Number ID.

3. (Optional) Paste your WABA ID (or press Enter to skip).

4. The CLI will verify your phone number directly with Meta and save credentials locally at ~/.was-whatsapp-cloud-mcp/config.json with strict 0600 permissions.

Step 3 — Add to Your AI Client

Add the following configuration to your AI client's MCP configuration JSON file:

{
  "mcpServers": {
    "WhatsApp Cloud MCP": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-whatsapp-cloud-mcp"]
    }
  }
}

Configuration File Locations by Client:

• Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Cursor: ~/.cursor/mcp.json (or via Cursor Settings -> MCP)

• Google Antigravity / Windsurf: ~/.gemini/antigravity/mcp.json or ~/.codeium/windsurf/mcp_config.json

What You Can Ask the AI

Messaging & Notifications

• "Send a WhatsApp message to +15551234567 saying: 'Your appointment is confirmed for tomorrow at 3 PM!'."

• "Send the pre-approved template shipping_update to +15551234567 with order tracking details."

• "Send a PDF invoice to +15551234567 with the caption 'Invoice #1042'."

• "Send an interactive message to +15551234567 asking 'Do you want to confirm?' with Yes/No buttons."

Account & Templates

• "Check the quality rating and messaging limit tier of my WhatsApp phone number."

• "List all approved message templates under my WhatsApp Business Account."

Universal Escape Hatch

• "Make a GET request to /v22.0/{waba_id}/phone_numbers to list all registered phone numbers."

All Tools (7 Total)

CLI Commands

You can run these commands directly via npx -y github:mnsmasum62786/was-whatsapp-cloud-mcp <command>:

• auth — Interactive prompt to connect or re-connect your WhatsApp credentials.

• status — Show config file location, phone ID, and saved status.

• logout — Delete the locally stored credentials file (~/.was-whatsapp-cloud-mcp/config.json).

• help — Print command line usage and environment variable options.

Multi-Account Setup

You can bypass the local config file by setting environment variables in your client configuration. This allows running multiple WhatsApp phone numbers or client accounts simultaneously:

{
  "mcpServers": {
    "WhatsApp - Support Line": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-whatsapp-cloud-mcp"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "EAA...",
        "WHATSAPP_PHONE_NUMBER_ID": "105600000000001"
      }
    },
    "WhatsApp - Sales Line": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-whatsapp-cloud-mcp"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "EAA...",
        "WHATSAPP_PHONE_NUMBER_ID": "105600000000002"
      }
    }
  }
}

Troubleshooting

1. "WhatsApp Business Cloud API MCP — not configured yet"

• Cause: The MCP server was started before configuring credentials.

• Fix: Open your terminal and run npx -y github:mnsmasum62786/was-whatsapp-cloud-mcp auth.

2. "Recipient phone number not in allowed list"

• Cause: In Meta Developer sandbox mode, you can only message verified test phone numbers until you add a real payment method and business phone number.

• Fix: Add the recipient number under WhatsApp > API Setup > To in the Meta Developer Portal, or go Live.

3. "Template does not exist in language"

• Cause: The template name or language code provided does not match what was approved in Meta Business Suite.

• Fix: Run wa_list_templates to view exact template names and approved language codes.

4. Windows PowerShell Execution Policy Error

If you see an error like npx.ps1 cannot be loaded because running scripts is disabled:

• Fix: Run the following command in PowerShell:

  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

5. Cache Issues after Updates

To force clear the npx cache and download the latest release:

• Windows (PowerShell):

  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache" -ErrorAction SilentlyContinue
  npm cache clean --force

• Mac / Linux:

  rm -rf ~/.npm/_npx
  npm cache clean --force

License

MIT License. Built by Web Analytics Solution.