内容
# WBMCP
**WBMCP** 是一个适用于官方 WhatsApp Business Cloud API 的 MCP 服务器。它允许与 MCP 兼容的 AI 客户端使用 WhatsApp Business 工具发送消息、管理模板、处理媒体、读取账户详细信息和更新商业资料信息。
- GitHub: https://github.com/saravanaspar/WBMCP
- npm: https://www.npmjs.com/package/wbmcp
```bash
npx -y wbmcp@latest setup
```
## 关于 WhatsApp Cloud API 的重要注意事项
WBMCP 使用 **WhatsApp Business Cloud API**。
当您为 WhatsApp Business 号码使用 Cloud API 时，请不要期望该 API 连接的工作流能够提供正常的 WhatsApp Business 应用或 WhatsApp Web 体验。该 API 允许软件访问 WhatsApp Business 账户，但它本身并不提供收件箱 UI。
如果您想接收客户消息、查看对话并从屏幕回复，您需要以下之一：
- 具有聊天界面的您自己的 SaaS 或商业应用
- 接受 WhatsApp Business API 凭证的第三方收件箱/聊天平台
- 您自己的 webhook 接收器、消息数据库和回复 UI
WBMCP 是 AI/MCP 工具层。它可以帮助 AI 客户端执行 WhatsApp Business API 操作，但它不是完整的收件箱、CRM、支持仪表板或 WhatsApp Business 应用替代品。
## 它能做什么
WBMCP 公开 WhatsApp Business Cloud API 操作作为 MCP 工具。
主要功能：
- 发送文本消息
- 发送模板消息
- 发送图片、文档、音频和视频消息
- 发送位置和联系人消息
- 发送交互式按钮和列表消息
- 标记消息为已读
- 列出和检查消息模板
- 创建和删除模板
- 获取和删除媒体
- 获取和更新商业资料信息
- 获取 WhatsApp Business 账户信息
- 列出电话号码
- 验证电话号码和模板有效载荷
- 向 MCP 客户端公开只读账户资源
## 它不能做什么
WBMCP 不提供：
- WhatsApp Business 应用登录
- WhatsApp Web 登录
- 客户收件箱 UI
- 团队收件箱
- 会话存储
- webhook 托管
- CRM 功能
- 活动或批量消息软件
- 用户的公共 REST API
- 绕过 Meta 或 WhatsApp 策略限制的方法
如果您的产品需要入站消息和回复，请构建或使用支持 WhatsApp Business API 凭证的聊天界面。
## 安装
运行：
```bash
npx -y wbmcp@latest setup
```
设置命令将凭证本地保存到：
```text
~/.config/wbmcp/config.json
```
设置完成后，MCP 客户端可以启动 WBMCP：
```bash
npx -y wbmcp@latest
```
## 设置
设置向导会询问：
1. WhatsApp 访问令牌
2. WhatsApp 电话号码 ID
3. WhatsApp Business 账户 ID
您可以从 Meta 获取这些信息：
- Meta for Developers：https://developers.facebook.com/apps/
- WhatsApp Cloud API 指南：https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
- 生产系统用户令牌：https://business.facebook.com/settings/system-users
对于快速测试，请使用 Meta 应用中 **WhatsApp > API 设置** 中显示的临时令牌。
对于生产环境，请使用具有以下权限的永久系统用户令牌：
```text
whatsapp_business_messaging
whatsapp_business_management
```
请勿将真实令牌提交到 GitHub。
## MCP 客户端设置
WBMCP 可以通过两种方式配置：
1. **保存的本地配置**：运行 `npx -y wbmcp@latest setup` 一次，然后保持 MCP 客户端配置不包含机密信息。这对于本地开发是推荐的。
2. **MCP 环境配置**：在 MCP 客户端配置的 `env` 块中放置 WhatsApp 凭证。这对于 CI、容器、托管代理或不想运行设置向导的机器很有用。
WBMCP 首先从进程环境变量中读取凭证，然后回退到 `~/.config/wbmcp/config.json`。因此，MCP 客户端传递的环境值会覆盖保存的设置值。
必需的环境值：
```text
WHATSAPP_ACCESS_TOKEN=您的 Meta 系统用户或临时令牌
WHATSAPP_PHONE_NUMBER_ID=您的 Meta 电话号码 ID
WHATSAPP_BUSINESS_ACCOUNT_ID=您的 Meta Business 账户 ID
```
常见的可选环境值：
```text
WHATSAPP_GRAPH_API_VERSION=v24.0
MCP_ENABLE_DANGEROUS_TOOLS=false
MCP_LOG_LEVEL=info
WHATSAPP_APP_SECRET=您的 Meta 应用密钥
```
`MCP_ENABLE_DANGEROUS_TOOLS=true` 是发送、创建、更新或删除数据的工具所必需的。将其保持为 `false` 以进行只读使用。
### OpenCode
保存配置模式：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"WBMCP": {
"type": "local",
"command": [
"npx",
"-y",
"wbmcp@latest"
],
"enabled": true,
"timeout": 15000
}
}
}
```
环境配置模式：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"WBMCP": {
"type": "local",
"command": [
"npx",
"-y",
"wbmcp@latest"
],
"enabled": true,
"timeout": 15000,
"env": {
"WHATSAPP_ACCESS_TOKEN": "用您的访问令牌替换",
"WHATSAPP_PHONE_NUMBER_ID": "用您的电话号码 ID 替换",
"WHATSAPP_BUSINESS_ACCOUNT_ID": "用您的商业账户 ID 替换",
"WHATSAPP_GRAPH_API_VERSION": "v24.0",
"MCP_ENABLE_DANGEROUS_TOOLS": "false"
}
}
}
}
```
然后启动 OpenCode：
```bash
opencode
```
示例提示：
```text
使用 WBMCP 并列出可用的 WhatsApp 工具。
```
首先使用只读检查，然后再发送消息：
```text
使用 WBMCP 获取我的 WhatsApp Business 账户信息。
```
### Codex CLI
保存配置模式：
```bash
npx -y wbmcp@latest setup
codex mcp add WBMCP -- npx -y wbmcp@latest
```
或者让 WBMCP 更新 Codex MCP 配置：
```bash
npx -y wbmcp@latest setup codex
```
环境配置模式适用于 `~/.codex/config.toml`:
```toml
[mcp_servers.WBMCP]
command = "npx"
args = ["-y", "wbmcp@latest"]
startup_timeout_sec = 20
[mcp_servers.WBMCP.env]
WHATSAPP_ACCESS_TOKEN = "用您的访问令牌替换"
WHATSAPP_PHONE_NUMBER_ID = "用您的电话号码 ID 替换"
WHATSAPP_BUSINESS_ACCOUNT_ID = "用您的商业账户 ID 替换"
WHATSAPP_GRAPH_API_VERSION = "v24.0"
MCP_ENABLE_DANGEROUS_TOOLS = "false"
```
`setup codex` 助手会编写一个干净的基于命令的配置，该配置使用保存的 WBMCP 配置文件。如果您更喜欢环境配置模式，请手动编辑 `~/.codex/config.toml`。
### Claude Desktop / Cursor 样式客户端
保存配置模式：
```json
{
"mcpServers": {
"WBMCP": {
"command": "npx",
"args": [
"-y",
"wbmcp@latest"
]
}
}
}
```
环境配置模式：
```json
{
"mcpServers": {
"WBMCP": {
"command": "npx",
"args": [
"-y",
"wbmcp@latest"
],
"env": {
"WHATSAPP_ACCESS_TOKEN": "用您的访问令牌替换",
"WHATSAPP_PHONE_NUMBER_ID": "用您的电话号码 ID 替换",
"WHATSAPP_BUSINESS_ACCOUNT_ID": "用您的商业账户 ID 替换",
"WHATSAPP_GRAPH_API_VERSION": "v24.0",
"MCP_ENABLE_DANGEROUS_TOOLS": "false"
}
}
}
}
```
## SDK 用法
WBMCP 也可以作为 TypeScript SDK 导入到直接传递 WhatsApp 凭证的后端应用程序中，而不是启动本地 MCP 服务器进程。
```bash
npm install wbmcp
```
```ts
import { createWhatsAppBusinessClient } from "wbmcp/sdk";
const whatsapp = createWhatsAppBusinessClient({
accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
businessAccountId: process.env.WHATSAPP_BUSINESS_ACCOUNT_ID!,
graphApiVersion: "v24.0",
enableDangerousTools: true
});
await whatsapp.messages.sendText({
recipient_phone_number: "+15551234567",
message_body: "您好，来自 WBMCP SDK"
});
```
每个 MCP 工具都按 1:1 的比例公开在 `client.tools.<tool_name>` 下，并且为 `account`、`profile`、`messages`、`templates`、`media` 和 `safety` 提供了类型化的便捷命名空间。请参阅 [`docs/SDK.md`](docs/SDK.md) 以获取完整详细信息。
## 配置
建议为正常本地使用保存本地配置。环境变量也受支持，并且会覆盖保存的配置值。
必需：
```bash
WHATSAPP_ACCESS_TOKEN=用您的访问令牌替换
WHATSAPP_PHONE_NUMBER_ID=用您的电话号码 ID 替换
WHATSAPP_BUSINESS_ACCOUNT_ID=用您的商业账户 ID 替换
```
可选：
```bash
WHATSAPP_GRAPH_API_VERSION=v24.0
MCP_ENABLE_DANGEROUS_TOOLS=false
MCP_READ_ONLY=false
MCP_REQUIRE_CONFIRMATION=false
WHATSAPP_APP_SECRET=用您的应用密钥替换
```
默认本地传输：
```bash
MCP_TRANSPORT=stdio
```
请勿将可选机密设置为空字符串。省略未使用的可选变量。
## 危险工具
默认情况下，提供只读工具。发送、删除、创建或修改数据的操作被视为危险工具。
危险操作的示例：
- 发送 WhatsApp 消息
- 创建模板
- 删除模板
- 删除媒体
- 更新商业资料数据
- 标记消息为已读
仅在需要时启用危险工具：
```bash
MCP_ENABLE_DANGEROUS_TOOLS=true npx -y wbmcp@latest
```
请仅在具有明确业务授权的情况下使用这些工具。
### 只读模式
在测试、审计或连接必须不修改 WhatsApp 状态的 MCP 客户端时，使用只读模式：
```bash
MCP_READ_ONLY=true npx -y wbmcp@latest
```
在只读模式下，列表/获取/验证/安全工具仍然可用，但发送、删除、创建、注册、标记为已读和更新配置文件工具被阻止，即使启用了危险工具。
### 确认模式
在您希望危险工具需要显式第二次调用并带有 `confirm: true` 时，使用确认模式：
```bash
MCP_ENABLE_DANGEROUS_TOOLS=true MCP_REQUIRE_CONFIRMATION=true npx -y wbmcp@latest
```
如果没有确认，危险调用将返回一个结构化的 `confirmation_required` 错误，而不是调用 Meta。
### 试运行预览
发送工具支持 `dryRun: true`，以便代理可以预览预期的消息，而无需调用 Meta：
```json
{
"recipient_phone_number": "+15551234567",
"message_body": "您好，来自 WBMCP",
"dryRun": true
}
```
试运行响应使用与 `meta.mode = "dry_run"` 相同的 `{ ok, data, meta }` 结构。
## 消息结果
WBMCP 返回 Meta 的同步 Graph API 响应。
对于发送消息工具：
- 成功意味着 Meta 已接受发送请求
- 响应包括 WhatsApp 消息 ID（如果 Meta 提供）
- 成功并不意味着已送达
- 成功并不意味着已读
交付、已读和失败状态是异步的 webhook 事件。WBMCP 不托管 webhooks。
对于模板、媒体、配置文件和标记为已读的操作：
- 成功意味着 Meta 已接受或应用了 API 请求
- 如果 Meta 拒绝该操作，WBMCP 将返回一个清理后的错误
- WBMCP 不会绕过 Meta 的审查、策略、质量、配额或速率控制
## 接收消息
要接收客户消息并从 UI 回复，您的应用程序需要：
- Meta 中的 WhatsApp webhook 配置
- 公共 webhook 端点
- webhook 验证和签名验证
- 消息存储
- 会话状态
- 聊天界面
- 决定何时由人类或 AI 回复的逻辑
WBMCP 可用于该系统中的出站 AI 操作，但它不是完整的消息后端。
## 托管 HTTPS 模式
大多数用户应使用默认的本地 stdio 模式。
托管 HTTPS 模式仅适用于远程 MCP 客户端连接到托管的 WBMCP 服务器的部署。它需要 TLS 证书文件和 bearer 身份验证。
不支持纯 HTTP。
## 安全
请勿在日志、截图、GitHub 问题、聊天记录或已提交的文件中公开 WhatsApp 凭证。
推荐的控制措施：
- 使用最少权限的 Meta 系统用户令牌
- 定期轮换令牌
- 保持 `~/.config/wbmcp/config.json` 私有
- 避免在 MCP 客户端配置中直接存储机密
- 在生产工作流中启用危险工具调用前进行审查
通过 GitHub 私有顾问报告安全问题（如果可用）：
```text
https://github.com/saravanaspar/WBMCP/security/advisories
```
如果私有顾问不可用，请打开一个最小的 GitHub 问题，不含机密、令牌、客户数据、电话号码或消息内容。
## 开发
克隆：
```bash
git clone https://github.com/saravanaspar/WBMCP.git
cd WBMCP
npm install
```
运行检查：
```bash
npm run lint
npm run typecheck
npm test
npm run build
```
本地运行：
```bash
node dist/index.js --help
node dist/index.js setup
node dist/index.js
```
检查包内容：
```bash
npm pack --dry-run
```
## 免责声明
WBMCP 是一个独立项目。它与 Meta、WhatsApp、OpenAI、Anthropic、OpenCode、Cursor 或任何其他 AI 客户端供应商无关、不受其赞助或认可。
请根据 Meta 的平台条款、WhatsApp Business 策略和适用法律使用 WhatsApp Business Cloud API。
## 许可证
请参阅 [LICENSE](./LICENSE)。
## 更新日志
请参阅 [CHANGELOG.md](./CHANGELOG.md) 获取发行说明。
