# WhatsApp MCP Server

An MCP (Model Context Protocol) server that enables LLMs to interact with WhatsApp via the official **WhatsApp Cloud API** by Meta.

## Features

### Messaging Tools (13 tools)
| Tool | Description |
|------|-------------|
| `whatsapp_send_text` | Send text messages |
| `whatsapp_send_template` | Send approved template messages (required for initiating conversations) |
| `whatsapp_send_image` | Send images via URL |
| `whatsapp_send_document` | Send documents (PDF, DOCX, etc.) via URL |
| `whatsapp_send_location` | Send location pins |
| `whatsapp_send_contact` | Send contact cards |
| `whatsapp_send_reaction` | React to messages with emoji |
| `whatsapp_send_buttons` | Send interactive reply buttons (up to 3) |
| `whatsapp_send_list` | Send interactive list menus |
| `whatsapp_mark_as_read` | Mark messages as read (blue checkmarks) |
| `whatsapp_get_business_profile` | Retrieve your business profile |
| `whatsapp_update_business_profile` | Update business profile fields |
| `whatsapp_list_templates` | List approved message templates |

## Prerequisites

1. **Meta Developer Account** — Register at https://developers.facebook.com
2. **WhatsApp Business App** — Create a Meta app with the WhatsApp use case
3. **Access Token** — Generate from the WhatsApp API Setup panel
4. **Phone Number ID** — Found in the WhatsApp API Setup panel

### Getting Your Credentials

1. Go to [Meta for Developers](https://developers.facebook.com)
2. Create or select your app → Add the **WhatsApp** use case
3. In the WhatsApp API Setup panel, note:
   - **Phone Number ID** (numeric ID under your test number)
   - **WhatsApp Business Account ID** (for template operations)
4. Generate a **Temporary Access Token** (valid 24h) or set up a **System User** for a permanent token

## Setup

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment Variables

```bash
# Required
export WHATSAPP_ACCESS_TOKEN="your_access_token"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"

# Optional
export WHATSAPP_BUSINESS_ACCOUNT_ID="your_waba_id"  # Required for template operations
export WHATSAPP_API_VERSION="v23.0"                  # Default: v23.0
export TRANSPORT="stdio"                              # "stdio" (default) or "http"
export PORT="3000"                                    # HTTP port (default: 3000)
```

### 3. Build & Run

```bash
npm run build
npm start
```

## Usage with Claude Desktop

Add this to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/path/to/whatsapp-mcp-server/dist/index.js"],
      "env": {
        "WHATSAPP_ACCESS_TOKEN": "your_token",
        "WHATSAPP_PHONE_NUMBER_ID": "your_phone_id",
        "WHATSAPP_BUSINESS_ACCOUNT_ID": "your_waba_id"
      }
    }
  }
}
```

## Usage as HTTP Server

```bash
TRANSPORT=http PORT=3000 npm start
```

The server exposes:
- `POST /mcp` — MCP endpoint (Streamable HTTP)
- `GET /health` — Health check

## Important Notes

### 24-Hour Messaging Window
WhatsApp enforces a 24-hour customer service window. You can only send free-form messages (text, image, etc.) to users who have messaged you within the last 24 hours. Outside this window, you **must** use approved **template messages** to initiate contact.

### Phone Number Format
Always use international format without the `+` prefix (e.g., `353851234567` for an Irish number, `14155551234` for a US number).

### Rate Limits
The Cloud API supports up to 80 messages per second for standard tier. Monitor your usage in the Meta Business Manager.

## License

MIT