- 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。
HTTP_PROXY 或 HTTPS_PROXY 直接发送和连接。 从本地文件上传需要REST API。
您的 MCP 客户端显示每个工具的完整输入模式。HTTP 端点接受POST 和 DELETE. GET SSE 已禁用。
设备选择
每个通话按此顺序解析其设备:- 工具调用上的
device_id参数。 - MCP 连接上的
X-Device-Id头部。 - 唯一的注册设备,如果确有一个设备存在。
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).
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 账户登录。
