mcp-whatsapp-cloud

@codespar/mcp-whatsapp-cloud

适用于 WhatsApp Cloud API 的 MCP 服务——Meta 官方 WhatsApp Business API，托管在 Meta 基础设施上。

直接集成 Meta。 无中间商，也无服务商加价。适用于拥有已获批准的 WhatsApp Business Account（WABA），并希望享受 Meta 直连定价、全面掌控对话、定价类别和模板生命周期的商家。

本目录中的 WhatsApp 服务

服务	介绍	适用场景
whatsapp-cloud（本服务）	Meta Cloud API 直连	拥有已获批准的 WABA 的大型商家；规模化运营成本更低，无中间服务费
z-api	基于 Meta Cloud 的封装	轻松上手，即时 QR 配对，提供额外辅助功能
evolution-api	开源封装	可自托管，由社区驱动
take-blip	巴西 BSP 封装	面向巴西企业，具备 CCaaS 功能
zenvia	巴西 BSP 封装	巴西全渠道服务（SMS + WhatsApp）

工具（22）

工具	用途
send_text_message	发送纯文本消息。
send_template_message	发送已获批准的消息模板。
send_media_message	发送图片、视频、文档或音频。
send_interactive_message	发送交互式消息（回复按钮或列表）。
send_interactive_cta_url	发送带有单个 CTA URL 按钮的交互式消息。
send_interactive_flow	发送 WhatsApp Flow 消息。
send_location_message	发送位置图钉，包含纬度/经度，以及可选的名称/地址。
send_contacts_message	发送一个或多个联系人卡片（类似 vCard）。
send_reaction_message	对之前收到或发送的消息添加表情回应。
send_typing_indicator	在收到的消息上显示正在输入指示器。
mark_message_as_read	将收到的消息标记为已读，以便发送者看到蓝色双勾。
upload_media	上传媒体文件，并返回可在 send_media_message 中重复使用的 media_id。
retrieve_media_url	将 media_id 解析为短期有效的可下载 URL。
delete_media	按 ID 删除已上传的媒体资源。
list_templates	列出 WhatsApp Business Account 中的消息模板。
create_template	提交新模板以供 Meta 审核。
delete_template	按名称从 WABA 中删除消息模板。
get_business_profile	读取已配置的 WhatsApp 商业资料（简介、描述、电子邮件、网站、行业、地址）……
update_business_profile	更新已配置电话号码对应的商业资料。
list_phone_numbers	列出 WhatsApp Business Account 下注册的所有电话号码，包括显示名称、质量评级……
request_verification_code	请求 Meta 通过 SMS 或语音向已配置的电话号码发送验证码。
verify_code	提交通过 SMS/语音收到的验证码，该验证码是在调用 request_verification_code 后获取的。

安装

npm install @codespar/mcp-whatsapp-cloud

环境

WHATSAPP_ACCESS_TOKEN="EAAG..."           # required (secret) — Meta system-user token
WHATSAPP_PHONE_NUMBER_ID="1234567890"     # required — WABA phone number id
WHATSAPP_BUSINESS_ACCOUNT_ID="9876543210" # required — WABA id (for templates)
WHATSAPP_GRAPH_VERSION="v21.0"            # optional — Meta bumps quarterly

身份验证

使用 Bearer 令牌访问 Graph API。请使用来自 Meta Business Manager 的永久系统用户令牌——用户访问令牌会过期，导致生产环境无法正常运行。

Authorization: Bearer <WHATSAPP_ACCESS_TOKEN>

消息规则（重要）

• 客户服务窗口——用户最后一次给你发送消息后的 24 小时内，你可以自由发送任何类型的消息。
• 商家主动发起——超出此时间窗口后，必须发送已获批准的模板。使用 send_template_message，并提供名称、语言和组件。
• 模板——使用 create_template 创建，等待 Meta 审核（数分钟至数小时），然后即可使用。
• 电话号码必须采用 E.164 格式，且不带开头的 +（例如 5511999999999）。

媒体

两种方式：

1. 公开 URL——将 link 传递给 send_media_message。速度最快，但 Meta 每次发送时都会获取内容。
2. 已上传的 media_id——调用一次 upload_media，后续发送时重复使用 id。推荐用于目录资源。

已上传的媒体约 30 天后过期。

交互式消息

send_interactive_message 需要一个完整的 interactive 对象。按钮载荷示例：

{
  "type": "button",
  "body": { "text": "Confirma seu pedido?" },
  "action": {
    "buttons": [
      { "type": "reply", "reply": { "id": "confirm", "title": "Confirmar" } },
      { "type": "reply", "reply": { "id": "cancel", "title": "Cancelar" } }
    ]
  }
}

列表载荷请参阅 Cloud API 交互式参考。

运行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-whatsapp-cloud

# HTTP (for server-to-server)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-whatsapp-cloud

企业版

需要为 Agent 付款设置治理、预算限额和审计跟踪？CodeSpar Enterprise 在这些 MCP 服务的基础上，新增了策略引擎、付款路由和合规模板。

许可证

MIT