# mcp-whatsapp-cloud

An MCP server for the WhatsApp Cloud API. Your agent sends messages, media and templates through Meta's Graph API directly.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/communication/whatsapp-cloud
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-whatsapp-cloud

## What it does

The server exposes 22 tools to an agent. Plain text, approved templates, images and documents, interactive replies with buttons or lists, location pins, contact cards, emoji reactions. A second group handles media: upload a file, resolve a `media_id` to a download URL, delete an asset. Templates and the business profile are covered too.

Auth is a Bearer token against the Graph API. You need a permanent system-user token from Meta Business Manager, because user tokens expire and will break production. Three environment variables are required: `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` and `WHATSAPP_BUSINESS_ACCOUNT_ID`. The Graph version is optional. Phone numbers go in E.164 without the leading `+`.

Messaging rules matter here. For 24 hours after the user's last message you can send anything; past that window only an approved template goes through. Templates are created first and then wait on Meta's review. Uploaded media expires after roughly 30 days, so catalog assets are better kept as a link or re-uploaded. This server targets merchants with an approved WhatsApp Business Account who want Meta-direct pricing and no intermediary fees.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_BUSINESS_ACCOUNT_ID`, `WHATSAPP_GRAPH_VERSION` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> --env WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> --env WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> --env WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> --transport stdio whatsapp-cloud -- npx -y @codespar/mcp-whatsapp-cloud
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add whatsapp-cloud --env WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> --env WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> --env WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> --env WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> -- npx -y @codespar/mcp-whatsapp-cloud
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "whatsapp-cloud": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-whatsapp-cloud"
            ],
            "env": {
                "WHATSAPP_ACCESS_TOKEN": "<WHATSAPP_ACCESS_TOKEN>",
                "WHATSAPP_PHONE_NUMBER_ID": "<WHATSAPP_PHONE_NUMBER_ID>",
                "WHATSAPP_BUSINESS_ACCOUNT_ID": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
                "WHATSAPP_GRAPH_VERSION": "<WHATSAPP_GRAPH_VERSION>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "whatsapp-cloud": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-whatsapp-cloud"
            ],
            "env": {
                "WHATSAPP_ACCESS_TOKEN": "<WHATSAPP_ACCESS_TOKEN>",
                "WHATSAPP_PHONE_NUMBER_ID": "<WHATSAPP_PHONE_NUMBER_ID>",
                "WHATSAPP_BUSINESS_ACCOUNT_ID": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
                "WHATSAPP_GRAPH_VERSION": "<WHATSAPP_GRAPH_VERSION>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e WHATSAPP_ACCESS_TOKEN=<WHATSAPP_ACCESS_TOKEN> -e WHATSAPP_PHONE_NUMBER_ID=<WHATSAPP_PHONE_NUMBER_ID> -e WHATSAPP_BUSINESS_ACCOUNT_ID=<WHATSAPP_BUSINESS_ACCOUNT_ID> -e WHATSAPP_GRAPH_VERSION=<WHATSAPP_GRAPH_VERSION> whatsapp-cloud npx -y @codespar/mcp-whatsapp-cloud
```
Replace <…> with your own values

## When to use it
- send a text or template to a customer from the agent
- upload an image once and reuse its `media_id`
- build an interactive message with confirm and cancel buttons
- submit a template and wait for Meta approval
- mark an incoming message as read

## Example prompts
- Send the `order_confirmed` template to `5511999999999` in Portuguese
- Upload `catalog.png` and reply with it to the last message
- Build an interactive message with Confirm and Cancel reply buttons

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [OpenWork MCP Gateway](https://affpapa.org/en/nevibecode/mcp/openwork-mcp-gateway.md) — MCP server · ★ 24242
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9366
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7506

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md