WhatsApp MCP Server with Wati API

使用 Wati API v3 的 WhatsApp MCP 服务

提示

Wati 现已提供官方托管的 MCP 服务。 无需安装，也无需 API 密钥：连接 https://mcp.wati.io/mcp（欧盟：https://eu-mcp.wati.io/mcp），并通过 OAuth 登录。它适用于 Claude、ChatGPT、Meta Muse、Cursor 等，也能管理 Astra AI Agent。设置指南：wati-io/wati-mcp · 支持文章。如果有需要，仍可使用此可自托管服务。

这是一个使用 Wati API v3 的 WhatsApp 模型上下文协议（MCP）服务。

通过 Claude 等 AI 助手管理 WhatsApp 对话、联系人、模板、营销活动和渠道。搜索和阅读消息、发送文本和文件、管理联系人并自动化工作流——全部通过 MCP 工具完成。

如需获取此项目及其他项目的更新，请在此输入电子邮件地址

v0.2.0 版本更新内容

破坏性变更： 此版本将旧版 Wati v1 API 迁移至 v3 API（/api/ext/v3/*）。

变更

• 迁移至 API v3 — 所有端点均已更新为 /api/ext/v3/* 路径
• URL 方案 — 租户 ID 不再嵌入 URL 路径；改为从 Bearer 令牌解析
• WATI_TENANT_ID 现为可选项 — 仅在多渠道设置（按 Channel:PhoneNumber 定向）时需要
• 新增工具： list_contacts、get_contact、add_contact、update_contacts、get_contact_count、assign_contact_teams、send_file_via_url、send_interactive（按钮 + 列表）、assign_operator、update_conversation_status、list_templates、get_template、send_template、list_campaigns、get_campaign、list_channels
• 移除的工具： list_chats、get_chat、get_direct_chat_by_contact、get_contact_chats（由 list_contacts/get_contact/get_messages 替代）
• 简化响应解析 — v3 采用标准化的响应架构

迁移指南

1. 将 WATI_API_BASE_URL 更新为你的 Wati 服务地址（例如 https://live-mt-server.wati.io）
2. 除非使用多渠道定向，否则可以移除 WATI_TENANT_ID
3. 更新工具调用：send_message(recipient=...) → send_message(target=...)
4. 使用 list_contacts/get_contact + get_messages 替换 list_chats/get_chat

安装

通过 Smithery 安装

npx -y @smithery/cli install @wati-io/wati-mcp-server --client claude

前置条件

• Python 3.11+
• Anthropic Claude 桌面应用（或 Cursor）
• UV（Python 包管理器），使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
• Wati API 访问权限（需要认证令牌）

步骤

1. 克隆此仓库

   git clone https://github.com/wati-io/wati-mcp-server.git
   cd wati-mcp-server
   

2. 配置 Wati API

   复制示例环境文件，并填入你的 Wati API 凭据：

   cp .env.example .env
   # Edit .env with your Wati API credentials
   

   必填：

   • WATI_API_BASE_URL：Wati API 的基础 URL（例如 https://live-mt-server.wati.io）
   • WATI_AUTH_TOKEN：你的 Wati 认证令牌（来自控制面板的 Bearer 令牌）

   可选：

   • WATI_TENANT_ID：你的 Wati 租户 ID（仅用于多渠道设置）

3. 连接 MCP 服务

   复制以下 json，并填入相应的 {{PATH}} 值：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}",
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/wati-mcp-server",
           "run",
           "main.py"
         ]
       }
     }
   }
   

   对于 Claude，将其保存为 claude_desktop_config.json，路径为：

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

   对于 Cursor，将其保存为 mcp.json，路径为：

   ~/.cursor/mcp.json
   

4. 重启 Claude Desktop / Cursor

MCP 工具

联系人

• search_contacts — 按姓名或电话号码搜索联系人
• list_contacts — 分页列出联系人
• get_contact — 按电话号码或 ID 获取联系人详细信息
• add_contact — 添加新的 WhatsApp 联系人
• update_contacts — 批量更新联系人的自定义参数
• get_contact_count — 获取联系人总数
• assign_contact_teams — 将联系人分配给团队

消息与对话

• get_messages — 获取联系人的对话消息
• send_message — 发送文本消息
• send_file — 通过上传发送文件（图片、视频、文档、音频）
• send_file_via_url — 通过 URL 发送文件（无需下载到本地）
• download_media — 下载消息中的媒体
• send_interactive — 发送交互式按钮或列表消息
• assign_operator — 为对话分配客服
• update_conversation_status — 更新对话状态（open/solved/pending/block）

模板

• list_templates — 列出消息模板
• get_template — 获取模板详情
• send_template — 向接收者发送模板消息

营销活动

• list_campaigns — 列出广播营销活动
• get_campaign — 获取营销活动详情和统计数据

渠道

• list_channels — 列出可用的 WhatsApp 渠道

架构

Claude/AI Assistant
    ↕ MCP Protocol (stdio)
Python MCP Server (FastMCP)
    ↕ HTTPS + Bearer Auth
Wati API v3
    ↕
WhatsApp Business

1. Claude 通过 MCP 协议向 Python MCP 服务发送请求
2. MCP 服务向 Wati v3 API 发起经过身份验证的 API 调用
3. Wati API 与 WhatsApp 后端通信
4. 数据沿调用链返回给 Claude

故障排除

• 身份验证错误：确保 WATI_AUTH_TOKEN 有效且未过期
• 404 错误：确保 WATI_API_BASE_URL 指向正确的 Wati 服务
• 速率限制：Wati API 有速率限制。如果触发限制，请稍候或联系 Wati 支持
• 媒体上传失败：检查文件类型支持情况和大小限制
• uv 权限问题：将其添加到 PATH，或使用可执行文件的完整路径

如需 MCP 集成故障排除，请参阅 MCP 文档。