跳转到主要内容
GOWA服务于与REST API相同进程的 Model Context Protocol 端点。 任何支持 简化HTTP 传输的 MCP 客户端可以通过它发送消息、阅读聊天并管理群组。
  • URL: http://<host>:3000<APP_BASE_PATH>/mcp (默认 http://localhost:3000/mcp)
  • 默认启用。使用 MCP_ENABLED=false 或 --mcp-enabled=false 禁用。
  • 无状态:没有会话握手以保持通话之间的存活。
从旧版本升级?独立的 ./whatsapp mcp 命令及其位于端口 8080 的 SSE 端点(/sse)已被移除。请运行 ./whatsapp rest,并将客户端指向 /mcp。原先每项操作对应一个工具的工具集已替换为下方的整合工具。

连接客户端

/mcp 与 REST API 使用相同的 Basic Auth 认证。请发送 Authorization 请求头;如果运行多个设备,还需发送 X-Device-Id:
YWRtaW46Y2hhbmdlbWU= 是 base64("admin:changeme") 的结果;使用 echo -n 'user:pass' | base64 生成自己的值。如果未启用 Basic Auth,可省略 Authorization;如果只有一个设备,可省略 X-Device-Id。 具体的配置格式取决于客户端。如果客户端只能启动 stdio 服务器,请使用 mcp-remote 等桥接工具。

工具

GOWA 暴露了7个工具。每个工具都需要一个选择操作的 type (send) 或 action (所有其他) 参数。 关于参数的说明:
  • whatsapp_send 总是需要 type 和 phone 。媒体**只能通过 URL 发送(image_url, video_url, audio_url, file_url, sticker_url); MCP 无法上传本地文件。 link 需要link 和 caption;forward 需要message_id。
  • whatsapp_send 接受定时发送字段(scheduled_at, timezone, recurrence, weekdays, day_of_month, end_at, occurrence_limit)。使用 whatsapp_schedule 管理生成的计划(get、pause、resume 和 cancel 需要 schedule_id)。
  • whatsapp_message 需要 phone (聊天)和message_id; edit 也需要 message 。
  • 在 v9.9.0 之后的 GOWA main 分支中,使用 action: "edit" 的 whatsapp_message 支持通过 media_type: "image" 或 media_type: "document" 替换说明文字。媒体类型须与原始媒体一致,并省略 link。参见编辑说明文字。
  • whatsapp_chat: get_messages 需要 chat_jid; archive 需要 chat_jid 和 archived。
  • whatsapp_app: login_code 需要 phone 。
实验按钮、位置请求和旋转轮播送只能通过 REST 提供。请参阅交互消息。 通讯工具支持频道发现、历史计数器和自动续订实时更新订阅。见 newsletters。 媒体URL下载应用相同的公共地址检查,无需使用 HTTP_PROXY 或 HTTPS_PROXY 直接发送和连接。 从本地文件上传需要REST API。 您的 MCP 客户端显示每个工具的完整输入模式。HTTP 端点接受POST 和 DELETE. GET SSE 已禁用。

设备选择

每个通话按此顺序解析其设备:
  1. 工具调用上的 device_id 参数。
  2. MCP 连接上的 X-Device-Id 头部。
  3. 唯一的注册设备,如果确有一个设备存在。
否则通话无法使用 device identification required: set the X-Device-Id header or pass device_id 。请见 Multi-device。

使用 OAuth 的远程客户端

托管客户端,如Claude 自定义连接器不能附加基本认证头部。 对于他们,GOWA可以运行 /mcp 的 OAuth 2.1 授权服务器。默认情况下是关闭的。
要求和行为:
  • APP_BASIC_AUTH 必须设置:授权页面在这些账户中标记用户。没有授权页面启动失败。
  • 发行者和资源必须是 **public HTTPS ** URLs 客户端,没有像http://gowa:3000这样的内部地址。
  • 通过 OAuth 开启,/mcp 可以接受一个 或 基本认证。在REST 或UI 路由上不接受令牌。
  • 客户端注册(RFC 7591),注册机构限制在16KiB,每次重定向到2KiB。 注册次数限于每小时40次,储存1 000个客户;未使用客户在24小时后打印。
  • PKCE S256 是强制性的。 代码在5分钟后过期,在1小时后访问令牌;刷新令牌旋转,重用旧令牌撤销整个令牌家庭。 在MCP_OAUTH_DB_URI中只存储令牌的 SHA-256 哈希值(默认 file:storages/oauth.db).
重定向 URI 必须与注册值完全一致。原生客户端可以使用带动态端口的 HTTP 环回 IP 回调。localhost 回调必须明确指定端口并完全匹配。其他重定向必须使用 HTTPS。OAuth resource 绑定到规范 MCP URL;令牌请求可以省略它,但如果提供,其值必须匹配。授权成功的响应包含 iss。 在 OAuth 写入过程中打印过期的代码和代币。 旋转的刷新令牌哈希仍然存在,需要检测是否对一个在线家庭进行重放,最多持续30天的刷新令牌。 删除或替换 OAuth 数据库使现有客户端和赠款无效。 相对于签发者地址的端点:/oauth/authorize、/oauth/token、/oauth/register。发现元数据使用在域名根目录插入 well-known 路径的 URL,因此设置 APP_BASE_PATH=/gowa 时,代理必须路由以下路径:
检查来自外部的发现:
然后添加 https://gowa.example.com/mcp 作为自定义连接器,然后使用 APP_BASIC_AUTH 账户登录。
确保在 GOWA 前面的 Cloudflare Access 、 bot 挑战或认证代理不会拦截众所周知的 /oauth/* 或 /mcp 路径。 在代理服务器的/oauth/authorize上的比率限制失败。