# 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

| | Required | How to install |
|---|---|---|
| **Node.js 18+** | running `npx` | Mac: `brew install node` · Windows: https://nodejs.org · Linux: `apt install nodejs npm` |
| **Git** | letting `npx` clone from GitHub | Mac: `brew install git` (or first `git --version` triggers Xcode tools) · Windows: https://git-scm.com · Linux: `apt install git` |
| **Meta Developer Account** | to access WhatsApp Cloud API | [Meta for Developers](https://developers.facebook.com/) |
| **Meta Access Token & Phone ID** | for authentication | Walked through below |

## Quick Start — 3 Steps

### Step 1 — Get WhatsApp Cloud API Credentials

1. Go to [developers.facebook.com/apps](https://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:

```bash
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:

```json
{
  "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)

| Category | Tools | Description |
|---|---|---|
| **Messaging** | `wa_send_message` | Send plain text or markdown messages to a phone number. |
| | `wa_send_template` | Send pre-approved WhatsApp marketing/utility template messages. |
| | `wa_send_media` | Send image, document, video, audio, or sticker via direct URL. |
| | `wa_send_interactive_buttons` | Send interactive message with up to 3 quick-reply buttons. |
| **Management** | `wa_get_phone_number` | Inspect phone display name, verified status, and quality rating. |
| | `wa_list_templates` | List message templates, approval status, category, and languages. |
| **Universal API** | `wa_universal_api` | Invoke any WhatsApp Business Cloud API / Meta Graph endpoint directly. |

## 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:

```json
{
  "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:
  ```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)**:
  ```powershell
  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache" -ErrorAction SilentlyContinue
  npm cache clean --force
  ```
- **Mac / Linux**:
  ```bash
  rm -rf ~/.npm/_npx
  npm cache clean --force
  ```

## License

MIT License. Built by [Web Analytics Solution](https://webanalyticsbd.com/).