WhatsApp MCP Stream

WhatsApp MCP流


围绕以下内容构建的WhatsApp MCP服务器 可流式传输的HTTP 运输，使用 百利甜酒 用于WhatsApp连接，具有web管理UI和双向媒体流（上传+下载）。

要点：

• 传输：可流式HTTP /mcp
• 发动机：Baileys
• 管理UI：二维码、状态、注销、运行时设置
• 媒体：上传端点+ /media 主机+MCP下载工具

快速入门（Docker）

# build and run

docker compose build

docker compose up -d

服务器将在以下位置可用：

• 管理用户界面： http://localhost:3003/admin
• MCP端点： http://localhost:3003/mcp
• 媒体文件： http://localhost:3003/media/

运行时设置

可以在管理UI中编辑设置，并将其持久化到 SETTINGS_PATH （默认为 MEDIA_DIR/settings.json).

管理用户界面

Admin UI *具有运行时设置、QR链接、导出和状态的管理控制台。*

支持的设置：

• media_public_base_url
• upload_max_mb
• upload_enabled
• max_files_per_upload
• require_upload_token
• upload_token
• auto_download_media
• auto_download_max_mb

认证

尚未实现内置身份验证。在生产环境中，使用强制认证的网关。这个项目进展顺利 authmcp-gateway:

https://github.com/loglux/authmcp-gateway

媒体上传API

Base64 JSON格式：

curl -X POST http://localhost:3003/api/upload \
  -H "Content-Type: application/json" \
  -d {filename:photo.jpg,mime_type:image/jpeg,data:}

多部分（建议用于大文件）：

curl -X POST http://localhost:3003/api/upload-multipart \
  -F "file=@/path/to/file.jpg"

两人都回来了 url 以及（如果已配置） publicUrl.

上传身份验证（可选）

如果 require_upload_token=true，使用以下任一方式提供令牌：

• x-upload-token:
• Authorization: Bearer

MCP传输

服务器在以下位置公开Streamable HTTP /mcp.

典型流程：

1. POST /mcp 使用JSON-RPC initialize
2. 使用返回的 mcp-session-id 后续请求的标头
3. POST /mcp 用于工具调用

注意：客户必须发送 Accept: application/json, text/event-stream 上 initialize.

冒烟测试

MCP工具的快速回归烟雾：

npm run smoke:mcp

可选自定义目标：

MCP_BASE_URL=http://localhost:3003 npm run smoke:mcp

MCP工具

认证

联系人

聊天

消息

媒体

效用

恢复说明

此服务包含针对Baileys/WhatsApp会话状态损坏的有意恢复解决方法。

为什么存在：

• 在生产环境中，我们观察到容器仍然存活，MCP仍然应答，但WhatsApp会话功能中断。
• 最常见的指标是Baileys的错误，如 failed to find key ... to decode mutation 和 failed to sync state from version.
• 在这种状态下，手动重启容器通常会恢复服务。

当前行为：

• 根据应用程序状态损坏信号，该服务首先尝试通过以下方式进行软恢复 forceResync().
• 如果同一类故障在一个时间窗口内重复出现，则升级为内部WhatsApp客户端重启。
• 在断开连接时，例如 Connection Terminated，该服务会安排一个断开连接监视器，如果套接字没有返回，则升级为内部重启 open 迟早
• 重新连接生命周期防止嵌套锁死锁，因此断开连接恢复可以在不需要手动重新启动容器的情况下完成。
• 最近的生产观察显示插座反复断开(428 Connection Terminated, 503 Stream Errored)正在自动恢复到 open.
• 专注的 /healthz 端点报告 503 只有当服务真正卡在允许的恢复窗口之外时。
• Docker健康检查使用 /healthz，因此只有在进程内恢复有机会工作后，容器才会重新启动。

这些恢复机制减少了运营商的干预，提高了对常见WhatsApp/Baileys会话故障的恢复能力。

许可证

麻省理工学院

坚持

聊天和消息被持久化到会话卷中存储的本地SQLite数据库中。

环境变量：

其他运输诊断：

• /mcp POST请求现在将请求生命周期事件记录在 logs/mcp-whatsapp.log
• 这包括请求输入、传输调度、传输调度和传输调度， transport.handleRequest 完成和HTTP finish / close
• 使用这些日志来确定响应离开之前是否发生了延迟 whatsapp-mcp-stream 或者之后在网关/客户端

出口

通过以下方式导出聊天（JSON+可选下载媒体）：

GET /api/export/chat/:jid?include_media=true

如果 include_media=true，ZIP包括已通过下载的文件 download_media。它不会从WhatsApp获取丢失的媒体。