使用说明

WhatsApp MCP服务器

管理WhatsApp Business模板并从发送消息 Claude、ChatGPT、游标、VS代码副本，或由Meta Cloud API提供支持的任何MCP-兼容客户端。

它做什么

工具	说明
`validate_template`	在提交给Meta之前验证模板有效负载
`create_template`	提交模板以供Meta审批
`list_templates`	列出带有可选过滤器（状态、类别、名称）的模板
`get_template_detail`	按ID获取模板的完整详细信息
`check_template_status`	模板的快速状态检查
`delete_template`	按名称删除模板
`send_template_message`	将批准的模板发送到电话号码
`send_bulk_template_messages`	将批准的模板发送到多个电话号码

8工具 覆盖整个模板生命周期：创建→ 验证→ 批准→ send.

快速开始

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，创建或选择您的应用程序，导航至WhatsApp>API设置。

3.连接到您的MCP客户端

服务器支持 3种运输方式:

传输	命令	使用人
`stdio` （默认）	`python -m whatsapp_mcp`	克劳德桌面，光标，VS代码，Windsurf
`sse`	`python -m whatsapp_mcp --transport sse`	传统远程客户端
`streamable-http`	`python -m whatsapp_mcp --transport streamable-http`	Claude.ai、ChatGPT、较新的MCP客户端

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

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

克劳德桌面（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（远程-可流式传输http）

Claude.ai连接到远程MCP服务器自定义连接器。连接来自Anthropic的云服务器，而不是您的计算机。

在HTTPS之后，使用配置的env变量托管服务器：

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

使用nginx、Caddy或隧道（ngrok、Cloudflare隧道）将其置于HTTPS之后
在Claude.ai中：转到自定义>连接器 → 添加自定义连接器
输入您的服务器URL（例如。 https://your-domain.com/mcp/)
克劳德支持 无授权 或 基于OAuth 服务器。对于最简单的设置，将auth留空——服务器将使用您在步骤1中配置的env-var。

注： Claude.ai不支持自定义请求头。服务器必须通过环境变量预先配置Meta凭据。每个托管服务器为一个WhatsApp商业帐户提供服务。

Example nginx config

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（远程-响应API）

ChatGPT通过以下方式支持远程MCP服务器响应API。它支持流式HTTP和SSE传输。

选项1——服务器预先配置了env变量（最简单）：

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/mcp.json 在您的项目中：

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

VS代码副本（stdio）

添加 .vscode/mcp.json:

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

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

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

方法1——承载令牌（推荐）：

Base64使用您的Meta凭据对JSON对象进行编码：

# 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- 标题：**

标题	必填	描述
`X-Meta-Access-Token`	是	您的Meta访问令牌
`X-Meta-Phone-Number-Id`	是	您的WhatsApp电话号码ID
`X-Meta-Business-Account-Id`	是	您的WhatsApp商业帐户ID
`X-Meta-App-Id`	否	您的Meta应用ID（用于媒体上传）
`X-Meta-Api-Version`	没有	API版本（默认为v24.0）

如果Bearer令牌和X-Meta-*标头都不存在，服务器将回退到环境变量。

用法示例

连接后，只需与您的AI助手交谈：

“创建一个名为 summer_sale 带有标题图像、正文约50%的折扣和“立即购物”按钮

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

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

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

“检查模板ID 123456789的状态”

支持的模板类型

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

营销模板

结构变量	创建	发送	关键组件
文本/图像/视频/文档	✅	✅	页眉（可选）+正文+页脚+按钮
旋转木马	✅	✅	每张卡片都有标题、主体和按钮
目录	✅	✅	车身+ `CATALOG` 按钮
限时优惠（LTO）	✅	✅	车身+ `limited_time_offer` 组件+复制代码按钮
优惠券代码	✅	✅	车身+ `copy_code` 按钮
多产品消息（MPM）	✅	✅	车身+ `product_list` 分段行动
单一产品信息（SPM）	✅	✅	车身+ `product` 行动
产品卡片旋转木马	✅	✅	机身+带按钮的产品卡
呼叫权限	✅	—	车身+ `call_permission` 按钮

实用工具模板

结构变量	创建	发送	关键组件
文本/图像/视频/文档	✅	✅	页眉（可选）+正文+页脚+按钮
订单详细信息	✅	✅	车身+ `order_details` 带有支付有效载荷的按钮
订单状态	✅	✅	正文+订单状态参数

路由如何工作： 当你打电话的时候 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+
元WhatsApp商业帐户
系统用户访问令牌 whatsapp_business_messaging 和 whatsapp_business_management 权限

依赖项

包装	用途
`mcp`	模型上下文协议SDK
`httpx`	Meta API的异步HTTP客户端
`pydantic`	有效载荷验证
`python-dotenv`	环境配置

路线图

看 ROADMAP.md 对于计划中的功能。

许可证

麻省理工学院——见许可证.

建造于 Jina Connect --WhatsApp商业CX平台。