Whatsapp Business Mcp

WhatsApp MCP 服务

借助 Meta Cloud API，通过 Claude、ChatGPT、Cursor、VS Code Copilot 或任何兼容 MCP 的客户端管理 WhatsApp Business 模板并发送消息。

功能

8 个工具涵盖完整的模板生命周期：创建 → 验证 → 审批 → 发送。

快速开始

1. 克隆并安装

git clone https://github.com/nakulben/whatsapp-mcp.git
cd whatsapp-mcp
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 配置凭据

cp .env.example .env

META_ACCESS_TOKEN=your_access_token
META_WABA_ID=your_whatsapp_business_account_id
META_PHONE_NUMBER_ID=your_phone_number_id
META_APP_ID=your_app_id              # Optional, for media uploads
META_API_VERSION=v24.0               # Optional, defaults to v24.0

所有模式（本地 stdio 和托管远程模式）都会使用环境变量。

如何获取这些信息？ 前往 Meta for Developers，创建或选择你的应用，然后进入 WhatsApp > API Setup。

3. 连接到 MCP 客户端

该服务支持 3 种传输模式：

对于 HTTP 传输方式，你可以自定义主机/端口：

python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8000

Claude Desktop（stdio — 本地）

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_access_token",
        "META_WABA_ID": "your_waba_id",
        "META_PHONE_NUMBER_ID": "your_phone_number_id",
        "META_APP_ID": "your_app_id"
      }
    }
  }
}

Claude.ai Web（远程 — streamable-http）

Claude.ai 通过自定义连接器连接到远程 MCP 服务。连接由 Anthropic 的云服务器发起，而不是由你的计算机发起。

1. 配置好环境变量后，通过 HTTPS 托管该服务：

   python -m whatsapp_mcp --transport streamable-http --host 0.0.0.0 --port 8001
   

2. 通过 nginx、Caddy 或隧道（ngrok、Cloudflare Tunnel）为其配置 HTTPS
3. 在 Claude.ai 中：前往 Customize > Connectors → 添加自定义连接器
4. 输入你的服务 URL（例如 https://your-domain.com/mcp/）
5. Claude 支持无需身份验证或基于 OAuth 的服务。最简单的设置方式是将身份验证留空——服务将使用你在第 1 步配置的环境变量。

注意： Claude.ai 不支持自定义请求头。必须通过环境变量预先为服务配置 Meta 凭据。每个托管服务对应一个 WhatsApp Business Account。

location /mcp/ {
    proxy_pass http://127.0.0.1:8001/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

ChatGPT（远程 — Responses API）

ChatGPT 通过 Responses API 支持远程 MCP 服务。它同时支持 Streamable HTTP 和 SSE 传输方式。

选项 1 — 使用环境变量预先配置服务（最简单）：

from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

选项 2 — 通过 Bearer 令牌提供单次请求凭据：

将 Meta 凭据编码为 base64 JSON，并在 authorization 字段中传递。 OpenAI 会将此值作为 Authorization 请求头转发到你的 MCP 服务：

# Create the token
echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64
# Output: eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=

resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "whatsapp",
        "server_url": "https://your-domain.com/mcp/",
        "authorization": "eyJhY2Nlc3NfdG9rZW4iOiJFQUEuLi4iLCJwaG9uZV9udW1iZXJfaWQiOiIxMjMiLCJ3YWJhX2lkIjoiNDU2In0=",
        "require_approval": "never",
    }],
    input="List all my approved templates",
)

注意： ChatGPT 仅支持远程 MCP 服务（不支持本地 stdio）。你的服务必须可通过 HTTPS 从公网访问。

Cursor（stdio）

在项目的 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

VS Code Copilot（stdio）

添加到 .vscode/mcp.json：

{
  "servers": {
    "whatsapp": {
      "type": "stdio",
      "command": "/path/to/whatsapp-mcp/venv/bin/python",
      "args": ["-m", "whatsapp_mcp"]
    }
  }
}

按请求提供凭据（直接 HTTP / curl / 脚本）

对于程序化访问或自定义 MCP 客户端，你可以按请求传递凭据，而不必依赖服务端环境变量。支持两种方式：

方法 1 — Bearer 令牌（推荐）：

将包含 Meta 凭据的 JSON 对象进行 Base64 编码：

# Create the token
TOKEN=$(echo -n '{"access_token":"EAA...","phone_number_id":"123","waba_id":"456"}' | base64)

# Use it
curl -H "Authorization: Bearer $TOKEN" https://your-server.com/mcp/ ...

必填字段：access_token、phone_number_id、waba_id。可选字段：app_id、api_version。

方法 2 — X-Meta- 标头：*

如果既没有 Bearer 令牌，也没有 X-Meta-* 标头，服务端将回退到使用环境变量。

使用示例

连接后，直接与 AI 助手对话：

“创建一个名为 summer_sale 的营销模板，包含标题图片、关于 5 折优惠的正文，以及一个‘立即选购’按钮”

“列出我所有已批准的模板”

“将 order_confirmation 模板发送给 +919876543210，订单号为 ORD-456”

“在提交前验证此模板：……”

“检查模板 ID 123456789 的状态”

支持的模板类型

Meta 的 API 有 2 种模板类别（不包括 Authentication）。每个类别中的模板可以有不同的结构变体，每种变体都有自己的组件布局和验证规则。

营销模板

实用模板

**路由方式：**调用 create_template 时，服务端会检查组件以自动检测结构变体（例如，存在 cards[] → 轮播，CATALOG 按钮 → 商品目录），并应用相应的验证器。你只需传入 category: "MARKETING" 或 "UTILITY"——变体将根据组件结构确定。

运行测试

pip install pytest pytest-asyncio
python -m pytest tests/ -v

项目结构

whatsapp-mcp/
├── whatsapp_mcp/
│   ├── __init__.py          # Package version
│   ├── __main__.py          # Entry point (python -m whatsapp_mcp)
│   ├── config.py            # Environment config loader
│   ├── meta_api.py          # Async Meta Graph API client
│   ├── middleware.py         # ASGI middleware for per-request credentials
│   ├── server.py            # MCP server with 8 tools
│   ├── models/              # Pydantic data models
│   │   ├── body.py          # Body component
│   │   ├── header.py        # Header component (text/image/video/document)
│   │   ├── footer.py        # Footer component
│   │   ├── buttons.py       # Button types (URL, phone, quick reply, etc.)
│   │   ├── buttons_component.py
│   │   ├── enums.py         # Template categories, types, formats
│   │   └── order_models.py  # Order-related models (checkout templates)
│   └── validators/
│       ├── create/          # 12 template creation validators
│       └── send/            # 11 template send validators
├── tests/
│   ├── test_validators.py   # Validator tests
│   ├── test_meta_api.py     # API client tests (mocked HTTP)
│   └── test_tools.py        # MCP tool registration & helper tests
├── .env.example
├── requirements.txt
├── LICENSE                  # MIT
└── ROADMAP.md

要求

• Python 3.10+
• Meta WhatsApp Business Account
• 具有 whatsapp_business_messaging 和 whatsapp_business_management 权限的 System User 访问令牌

依赖项

路线图

请参阅 ROADMAP.md 了解计划中的功能。

许可证

MIT — 请参阅 LICENSE。

由 Jina Connect 构建——WhatsApp Business CX 平台。