WhatsApp MCP Stream

[

一个基于 Streamable HTTP 传输构建的 WhatsApp MCP 服务端，使用 Bailys 实现 WhatsApp 连接，并附带 Web 管理界面和双向媒体流（上传 + 下载）。

要点：

• 传输：位于 /mcp 的 Streamable HTTP

• 引擎：Baileys

• 管理界面：二维码、状态、退出登录、运行时设置、聊天历史记录查看器

• 媒体：上传端点 + /media 托管 + MCP 下载工具

快速开始（Docker）

# build and run

docker compose build

docker compose up -d

服务器可通过以下地址访问：

• 管理界面：http://localhost:3001/admin

• MCP 端点：http://localhost:3000/mcp

• 媒体文件：http://localhost:3000/media/<filename>

Related MCP server: WhatsApp Business API MCP Server

在带 --ifconfig=false 的主机上进行 DNS

在某些 NAS / 加固主机（例如启用了 dockerd --iptables=false 的 Synology）上，Docker 内嵌的 DNS 代理（127.0.0.11）没有 iptables DNAT 规则，因此会拒绝容器内的连接。

修复：复制 resolv.conf.example 到 resolv.conf，并添加一个卷覆盖：

cp resolv.conf.example resolv.conf

然后将和内容添加到本地 docker-compose.override.yml（不提交）：

services:
  mcp-whatsapp:
    volumes:
      - ./resolv.conf:/etc/resolv.conf:ro

docker compose up 会自动加载这个 override 文件。

运行时设置

设置可以在管理界面中编辑，并持久化到 SETTINGS_PATH（默认是 MEDIA_DIR/settings.json）。

管理界面

管理控制台，包括运行时设置、二维码关联、聊天记录查看器、导出和状态。

支持的设置：

• 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:<base64>}

Multipart（建议用于大文件）：

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

两者都会返回 url，并且（如果配置了）还会返回 publicUrl。

通过 send_media 发送本地文件

项目根目录中的 ./files/ 目录被绑定挂载到容器内的 /app/files 路径。把文件放到该目录后即可立即引用——无需重启容器：

# On host:
cp report.pdf /path/to/whatsapp-mcp-stream/files/

# In send_media:
media_path: /app/files/report.pdf

如果使用 URL 源，直接将 media_url 传给 send_media 或 stage_media 即可——服务器会自行下载文件，不用 base64。

上传认证（可选）

如果 require_upload_token=true，请通过以下任一方式提供 token：

• x-upload-token: <token>

• Authorization: Bearer <token>

MCP 传输

服务器在 /mcp 上暴露 Streamable HTTP。

典型流程：

1. 使用 JSON-RPC initialize 发送 POST /mcp

2. 在进行后续请求时使用返回的 mcp-session-id 请求头

3. 通过 POST /mcp 进行工具调用

注意：客户端在 initialize 时必须发送 Accept: application/json, text/event-stream。

Smoke 测试

对 MCP 工具进行的快速回归冒烟测试：

npm run smoke:mcp

可选的中的:

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

MCP 工具

认证

联系人

传输诊断附加信息：

• /mcp POST 请求现在会在 logs/mcp-whatsapp.log 中记录请求生命周期事件

• 其中包括请求进入、传输分发、transport.handleRequest 完成，以及 HTTP finish / close

• 使用这些日志判断延迟是发生在响应离开 whatsapp-mcp-stream 之前，还是之后在网关/客户端

聊天历史 API

通过以下接口浏览已存储的聊天和消息：

GET /api/chats?limit=50&offset=0&q=<search> — 分页聊天列表，可选择性按名称过滤。

GET /api/chats/jid/messages?limit=50&offset=0 — 聊天的分页消息（最新在前）。

两个接口均被 admin UI 中的 Chats 标签使用。

导出

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

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

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