内容
# WhatsApp MCP 服务器
> **用于 AI 代理的 WhatsApp 集成** — 发送消息、搜索聊天、分享媒体、审批工作流和智能活动摘要，适用于任何 MCP 客户端。设计为通过 [Docker MCP 工具包](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) 以容器化的 MCP 服务器运行。
> **致谢：** 作者非常了解 [kapso.ai](https://kapso.ai)，它提供了一个更强大、功能更完整的 WhatsApp 集成解决方案。这个项目是一个爱好者编码者带着太多好奇心、良好的系统设计直觉和现代 AI 辅助，决定看看他们能把周末项目推到多远。这是一个关于 MCP 服务器、容器化和 WhatsApp 协议集成的学习练习 — 这种事情如果放在几年前是很难尝试的，但现在由于更好的工具和 AI 的大量帮助，已经变得很有可能。
[](https://www.apache.org/licenses/LICENSE-2.0)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)
> **注意：** 该项目需要 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 并启用 [MCP 工具包](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)。或者，您可以使用 Docker Engine + Docker Compose（不使用 MCP 网关功能）。
---
## 为什么使用 Docker MCP 工具包？
该服务器在由 [Docker MCP 工具包](https://docs.docker.com/ai/mcp-catalog-and-toolkit/) 管理的 Docker 容器中运行，而不是直接在主机上运行。
| 优点 | Docker MCP 工具包 | 在主机上运行 |
|---------|-------------------|-----------------|
| **隔离** | WhatsApp 会话密钥、消息和媒体被限制在 Docker 卷中 — 不与您的普通文件混合 | 会话数据最终位于您的主目录中 |
| **安全边界** | 非 root、只读文件系统、权限被删除 | 以您的完整用户权限运行 |
| **多客户端网关** | 一个服务器实例同时为所有 MCP 客户端（Cursor、Claude Code、VS Code）提供服务，通过 MCP 网关 | 每个客户端都需要自己的服务器配置 |
| **机密管理** | 通过 `docker mcp secret set` 在 OS 密钥链中存储加密密钥，可从 Docker Desktop UI 配置 | 必须手动管理 `.env` 文件 |
| **主机依赖** | 不需要在您的机器上安装 Node.js、本地编译或 Go 二进制文件 | 必须安装 Node.js 18+、原生插件的构建工具和平台特定的二进制文件 |
| **可移植性** | 在 Windows、macOS 和 Linux 上运行（理论上 — 主要在 Windows 上测试） | 平台特定的原生依赖问题 |
| **生命周期管理** | 健康检查、自动重启、优雅关闭 — 全部由 Docker 处理 | 手动进程管理 |
| **干净的拆除** | `docker compose down -v` 删除所有内容 | 必须手动查找和清理数据文件、会话和进程 |
---
## 功能
- **34 个 MCP 工具** — 完整的 WhatsApp 控制：消息、媒体、搜索、联系人、群组、消息操作、审批、状态、实时交互、会话管理和分层工具文档
- **模糊名称匹配** — 说“John”或“book club”，服务器通过 Levenshtein 距离查找正确的聊天
- **媒体支持** — 下载接收的媒体并发送图片、视频、音频和文档
- **全文搜索** — SQLite FTS5 索引所有消息，支持关键字、短语和布尔运算符
- **智能补丁** — 一个工具，总结活跃的聊天、待处理的提问和未读的亮点
- **审批工作流** — 通过 WhatsApp 发送审批请求；收件人回复 APPROVE 或 DENY
- **配对码身份验证** — 基于文本的 8 位数字码身份验证，带有二维码图像回退（在容器内渲染，通过数据 URI 在任何浏览器中可见）
- **静止加密** — 消息正文、发件人姓名和媒体元数据的 AES-256-GCM 字段级加密
- **自动清除** — 配置的保留期后自动删除消息和媒体
- **已读回执和存在** — 可配置的送达回执（双勾）、已读回执（蓝色勾）和在线存在
- **会话恢复力** — 暂时的断开自动重新连接、启动重试、指数退避、60 秒健康心跳和会话过期时的 MCP 通知
- **会话持久性** — WhatsApp 会话通过 Docker 命名卷在容器重启后存活
- **长寿命容器** — 服务器在工具调用之间保持 WhatsApp WebSocket 连接活跃
- **欢迎群组** — 可选地创建 WhatsApp 群组并在首次连接时发送欢迎消息
---
## 快速入门
### 🚀 最小可行设置（5 分钟）
**想快速试用？** 无需克隆或构建 — 镜像将自动从 Docker Hub 拉取。
> **PowerShell 用户：** 在下面的命令中，将 `\`（反斜杠）替换为 `` ` ``（反引号）进行行延续。
>
> 示例：
> ```powershell
> docker mcp catalog create my-mcp --title "My MCP Servers" `
> --server file://./whatsapp-mcp-docker-server.yaml
> ```
```bash
# 0. 查找您的配置文件名称（Docker Desktop 创建“default”）
docker mcp profile list
# 1. 下载服务器定义文件（不需要完整的克隆）
curl -O https://raw.githubusercontent.com/Malaccamaxgit/whatsapp-mcp-docker/main/whatsapp-mcp-docker-server.yaml
# 2. 创建目录（一次性设置）
docker mcp catalog create my-mcp --title "My MCP Servers" \
--server file://./whatsapp-mcp-docker-server.yaml
# 3. 添加到您的配置文件（将“default”替换为步骤 0 中的配置文件名称）
docker mcp profile server add default \
--server file://./whatsapp-mcp-docker-server.yaml
# 4. 连接您的 MCP 客户端（将“cursor”替换为您的客户端 — 请参见下面的表格）
docker mcp client connect cursor --profile default
# 5. 重启/重新加载您的 MCP 客户端，以便它获取新的工具
# 6. 在您的客户端中，说：“使用 +1234567890 验证 WhatsApp”
```
**支持的客户端列表：** `cursor`、`claude-code`、`claude-desktop`、`vscode`、`gemini`、`goose` 等。运行 `docker mcp client connect --help` 查看完整列表。
**就这样！** 您现在已连接到 WhatsApp。镜像 (`malaccamax/whatsapp-mcp-docker:latest`) 将在首次使用时自动从 Docker Hub 拉取 — 无需构建步骤。
> **注意：** 连接后，您必须重启或重新加载您的 MCP 客户端，然后 WhatsApp 工具才会出现（请参见下面的完整设置中的客户端特定说明）。运行 `docker mcp tools ls` 在终端中仅显示 8 个 MCP 工具包元工具 — 34 个 WhatsApp 工具在客户端内部出现，网关在首次使用时启动容器。
>
> **重要：** 在某些 MCP 会话中，您可能需要显式激活配置文件，然后工具才可用。如果您遇到 `Error: Tool 'get_connection_status' not found in current session` 错误，请运行：
> ```bash
> docker mcp profile activate <your-profile>
> ```
> 或在 MCP 客户端会话内，使用 `mcp-activate-profile` 元工具。这是 Docker MCP 网关自动加载行为中已知的空白。
**下一步：** 设置加密和推荐的配置（如下）以安全使用。
---
### 📋 完整设置（推荐的安全配置）
### 0. 查找您的配置文件名称
Docker Desktop 创建一个名为 `default` 的配置文件。检查您自己的配置文件：
```bash
docker mcp profile list
```
在下面的步骤中，将 `<your-profile>` 替换为您显示的名称。
> **需要专用配置文件？** 在 Docker Desktop 中，前往 **MCP 工具包 → 配置文件** 并点击 **+** 创建一个，然后使用该名称。
### 1. 获取项目
**选项 A — 仅服务器 YAML（推荐大多数用户）：**
镜像将自动从 Docker Hub 拉取。您只需要服务器定义文件：
```bash
curl -O https://raw.githubusercontent.com/Malaccamaxgit/whatsapp-mcp-docker/main/whatsapp-mcp-docker-server.yaml
```
**选项 B — 完整克隆 + 本地构建（适用于开发者或自托管）：**
克隆并本地构建，如果您想修改源代码或在没有 Docker Hub 的情况下运行：
```bash
git clone https://github.com/Malaccamaxgit/whatsapp-mcp-docker.git
cd whatsapp-mcp-docker
docker compose build --no-cache
```
> **为什么使用 `--no-cache`？** BuildKit 的层缓存可能会在源文件更改时错误地缓存 TypeScript 编译。始终使用 `--no-cache` 以确保使用最新的编译代码。
> **留在包含 `whatsapp-mcp-docker-server.yaml` 的目录中** 以执行后续命令 — `file://./` 路径相对于您的当前工作目录。
### 2. 设置加密密钥
**设置加密密钥** （存储在 OS 密钥链中 — 不需要 `.env` 文件）：
```bash
# 选项 A：使用 Node.js（如果在主机上安装）— bash/zsh 仅限
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | docker mcp secret set whatsapp-mcp-docker.data_encryption_key
# 选项 B：使用 Docker（主机上不需要 Node.js）— bash/zsh 仅限
docker run --rm node:22-alpine node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | docker mcp secret set whatsapp-mcp-docker.data_encryption_key
```
> **Windows PowerShell 用户：** 管道 (`|`) 和重定向 (`<`) 运算符与 `docker mcp secret set` 在 PowerShell 上不起作用。使用此两步方法：
>
> ```powershell
> # 选项 A：使用 Python（推荐 — 避免 require() 转义问题）
> $key = docker run --rm python:3-alpine python3 -c "import base64,os; print(base64.b64encode(os.urandom(32)).decode())"
> docker mcp secret set "whatsapp-mcp-docker.data_encryption_key=$key"
>
> # 选项 B：使用 Node.js — 需要仔细引用；base64 字符 + / = 可能引起问题
> $key = docker run --rm node:22-alpine node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
> docker mcp secret set "whatsapp-mcp-docker.data_encryption_key=$key"
> ```
>
> 如果您看到“logon session does not exist” 错误，但密钥仍然出现在 `docker mcp secret ls` 中，则密钥已成功存储在 `docker-pass` 后端 — 错误是来自 Windows Credential Manager 后端的误导性警告，可以安全忽略。
**验证密钥已存储**（`docker mcp secret set` 成功时不产生确认）：
```bash
# bash/zsh
docker mcp secret ls | grep whatsapp
# PowerShell
docker mcp secret ls | findstr whatsapp
```
您应该看到一行包含 `whatsapp-mcp-docker.data_enc…`。
> **提示：** 保持生成的密钥安全！如果您丢失它，则加密的消息无法恢复。将其备份到密码管理器。
>
> **安全姿态：** 在没有 `DATA_ENCRYPTION_KEY` 的情况下运行处于不安全模式。仅在有明确操作员覆盖和记录的风险接受时执行此操作。
### 3. 创建自定义目录
在 [自定义目录](https://docs.docker.com/ai/mcp-catalog-and-toolkit/catalog/#custom-catalogs) 中注册服务器，以便它出现在 Docker Desktop 的 **目录** 选项卡中，与官方 Docker MCP 目录一起：
> **PowerShell 用户：** 在 Windows PowerShell 上，使用反引号（`` ` ``）而不是反斜杠（`\`）进行行延续。
>
> ```powershell
> docker mcp catalog create my-custom-mcp-servers `
> --title "My Custom MCP Servers" `
> --server file://./whatsapp-mcp-docker-server.yaml
> ```
```bash
docker mcp catalog create my-custom-mcp-servers \
--title "My Custom MCP Servers" \
--server file://./whatsapp-mcp-docker-server.yaml
```
在 Docker Desktop 中，前往 **MCP 工具包 → 目录** — **WhatsApp MCP** 服务器现在出现在您的自定义目录下，包含所有 34 个工具、配置选项和机密。
> **提示：** 要在代码更改后更新目录，请重新运行相同的命令 — 它会替换现有的条目。要添加更多服务器，请使用多个 `--server` 标志。
### 4. 添加到配置文件并应用配置
将服务器添加到配置文件中，以便 MCP 客户端可以使用它。
**选项 A — 从目录 UI：**
1. 在 **MCP 工具包 → 目录** 中，找到 **WhatsApp MCP** 下的自定义目录。
2. 选择服务器卡上的复选框。
3. 从下拉菜单中选择配置文件并确认。
**选项 B — CLI：
```bash
docker mcp profile server add <your-profile> \
--server file://./whatsapp-mcp-docker-server.yaml
```
**选项 C — Docker Desktop 配置文件：
1. 打开 Docker Desktop 并前往 **MCP 工具包 → 配置文件**。
2. 选择现有的配置文件（或创建一个新的）。
3. 在 **服务器** 部分，单击 **+** 并添加服务器。
所有选项都使用 `longLived: true`（持久容器）、`secrets`（来自 OS 密钥链的加密密钥）和所有 34 个工具注册服务器。
**添加后，应用推荐的配置：
> **PowerShell 用户：** 使用反引号（`` ` ``）而不是反斜杠（`\`）进行行延续。
>
> ```powershell
> docker mcp profile config <your-profile> `
> --set whatsapp-mcp-docker.rate_limit_per_min=60 `
> --set whatsapp-mcp-docker.message_retention_days=90 `
> --set whatsapp-mcp-docker.send_read_receipts=true `
> --set whatsapp-mcp-docker.auto_read_receipts=true `
> --set whatsapp-mcp-docker.presence_mode=available `
> --set whatsapp-mcp-docker.welcome_group_name=WhatsAppMCP `
> --set whatsapp-mcp-docker.auth_wait_for_link=false `
> --set whatsapp-mcp-docker.auth_link_timeout_sec=120 `
> --set whatsapp-mcp-docker.auth_poll_interval_sec=5
> ```
```bash
docker mcp profile config <your-profile> \
--set whatsapp-mcp-docker.rate_limit_per_min=60 \
--set whatsapp-mcp-docker.message_retention_days=90 \
--set whatsapp-mcp-docker.send_read_receipts=true \
--set whatsapp-mcp-docker.auto_read_receipts=true \
--set whatsapp-mcp-docker.presence_mode=available \
--set whatsapp-mcp-docker.welcome_group_name=WhatsAppMCP \
--set whatsapp-mcp-docker.auth_wait_for_link=false \
--set whatsapp-mcp-docker.auth_link_timeout_sec=120 \
--set whatsapp-mcp-docker.auth_poll_interval_sec=5
```
或者，通过 Docker Desktop：**MCP 工具包 → WhatsApp MCP → 配置 / 机密**。
此操作会填充 Docker Desktop 中的配置字段，以便您可以从 UI 中查看和调整它们。 如果没有此步骤，服务器仍然有效（默认在运行时应用），但 UI 字段出现空白。
`auth_*` 键为 **`authenticate`** 工具设置默认值，当您省略 `waitForLink`、`linkTimeoutSec` 或 `pollIntervalSec` 时：是否等待设备链接后显示配对代码或二维码，最大等待时间（秒）和如何轮询（秒）。 `auth_wait_for_link=false` 是默认推荐设置，大多数客户端推荐此设置以避免工具调用超时。 将 `auth_wait_for_link=true` 仅在没有工具调用超时且您希望工具自动确认的情况下设置。### 5. 连接您的 MCP 客户端
使用一个命令将您的 AI 客户端连接到配置文件，替换您的客户端名称：
```bash
docker mcp client connect <your-client> --profile <your-profile>
```
支持的客户端名称： `cursor`、`claude-code`、`claude-desktop`、`vscode`、`gemini`、`goose` 等。运行 `docker mcp client connect --help` 查看完整列表。
此操作会自动将 MCP 网关条目添加到客户端的配置文件中。 **连接后，请重启或重新加载您的客户端，以便它获取新的服务器：
| 客户端 | 如何重新加载 |
|--------|---------------|
| **Cursor** | `Ctrl+Shift+P` → **Reload Window` |
| **Claude Desktop** | 退出并重新打开应用程序 |
| **Claude Code** | 运行 `claude mcp restart` 或重启会话 |
| **VS Code** | 重新加载窗口或重启 MCP 扩展 |
| **Goose / Gemini CLI** | 重启会话 |
> **为什么 `docker mcp tools ls` 不显示我的 34 个工具？** 该命令仅显示 8 个 MCP 工具包元工具（例如 `mcp-add`、`mcp-find`）。 34 个 WhatsApp 工具在您的 MCP 客户端内部显示，网关在第一次工具调用时启动 `whatsapp-mcp-docker` 容器。它们在终端中不可见。
要在**手动**连接时，请直接在客户端配置文件中添加 MCP 网关条目。有关每个支持的客户端的现成代码段，请参阅 [`examples/client-configs.md`](./examples/client-configs.md)。每个客户端将其配置文件存储在不同的位置 — 请参阅客户端文档以获取确切的路径。条目格式为：
```json
{
"mcpServers": {
"MCP_DOCKER": {
"command": "docker",
"args": ["mcp", "gateway", "run", "--profile", "<your-profile>"]
}
}
}
```
> **Windows 用户：** `docker mcp client connect` 命令会自动注入所需的 Windows 环境变量 (`LOCALAPPDATA`, `ProgramData`, `ProgramFiles`). 如果您手动编辑配置文件，必须添加它们，否则网关将无法定位凭证：
>
> ```json
> {
> "mcpServers": {
> "MCP_DOCKER": {
> "command": "docker",
> "args": ["mcp", "gateway", "run", "--profile", "<your-profile>"],
> "env": {
> "LOCALAPPDATA": "C:\\Users\\<you>\\AppData\\Local",
> "ProgramData": "C:\\ProgramData",
> "ProgramFiles": "C:\\Program Files"
> }
> }
> }
> }
> ```
### 6. 身份验证
从您的MCP客户端：
```
Authenticate WhatsApp with my number +1234567890
```
服务器返回一个8位配对代码。在以下位置输入该代码：
**WhatsApp → 设置 → 已连接设备 → 连接设备 → 选择使用电话号码连接**
如果配对代码失败（速率限制或400错误），服务器会回落到二维码身份验证：
- **MCP图像块** - 显示支持图像渲染的客户端内联（例如Cursor，Claude Desktop）
- **数据URI** - 一个`data:image/png;base64,...`字符串包含在文本响应中；将其粘贴到任何浏览器的地址栏中以查看二维码 - 不需要主机工具
会话在`whatsapp-sessions`Docker卷中持续存在于容器重启。
**兼容客户端：** Claude Code，Claude Desktop，Cursor，VS Code，Gemini CLI，Goose，Cline，Gordon，Codex，以及任何支持模型上下文协议的客户端。运行`docker mcp client connect --help`以查看完整列表。
---
## 可用工具（34）
### 身份验证和状态
| 工具 | 描述 |
|------|-------------|
| `disconnect` | 注销并断开与WhatsApp的连接，清除会话 |
| `authenticate` | 通过8位配对码链接设备（二维码图像备用方案，带数据URI） |
| `get_connection_status` | 连接状态 + 数据库统计 |
### 消息
| 工具 | 描述 |
|------|-------------|
| `send_message` | 发送文本，模糊匹配联系人/群组名称 |
| `send_file` | 发送图片，视频，音频或文档，附带可选标题 |
| `list_messages` | 获取聊天中的消息，带日期范围过滤和分页 |
| `search_messages` | 跨所有消息的全文搜索（SQLite FTS5） |
### 联系人和聊天
| 工具 | 描述 |
|------|-------------|
| `list_chats` | 列出按最近活动排序的对话 |
| `search_contacts` | 按名称或电话号码查找联系人/群组 |
| `export_chat_data` | 为联系人或群组导出完整的聊天历史记录（JSON或CSV） |
### 媒体
| 工具 | 描述 |
|------|-------------|
| `download_media` | 从接收的消息下载媒体到持久存储 |
### 智能
| 工具 | 描述 |
|------|-------------|
| `catch_up` | 活动摘要：活跃聊天，问题，未读高亮 |
| `mark_messages_read` | 在聊天中将消息标记为已读 |
### 审批工作流
| 工具 | 描述 |
|------|-------------|
| `request_approval` | 发送审批请求 - 收件人回复APPROVE/DENY |
| `check_approvals` | 检查特定审批或列出所有待审批 |
**群组管理**
| 工具 | 描述 |
|------|-------------|
| `create_group` | 创建一个带有名称和参与者列表的新群组 |
| `get_group_info` | 获取群组的参与者，管理员，描述和设置 |
| `get_joined_groups` | 列出此帐户所属的所有群组 |
| `get_group_invite_link` | 获取群组的共享邀请链接（仅限管理员） |
| `join_group` | 通过邀请链接或代码加入群组 |
| `leave_group` | 永久离开群组 |
| `update_group_participants` | 添加，删除，推广或降级参与者（仅限管理员） |
| `set_group_name` | 重命名群组（仅限管理员） |
| `set_group_topic` | 设置或清除群组描述（仅限管理员） |
**消息操作**
| 工具 | 描述 |
|------|-------------|
| `send_reaction` | 对消息使用表情符号反应，或删除现有反应 |
| `edit_message` | 编辑以前发送的消息（自己的消息，在〜15分钟内） |
| `delete_message` | 删除已发送的消息以供所有人查看（撤销） |
**联系人和用户信息**
| 工具 | 描述 |
|------|-------------|
| `get_user_info` | 获取一个或多个电话号码的配置文件信息（可选`save_names`存储名称本地） |
| `is_on_whatsapp` | 检查电话号码是否有WhatsApp帐户 |
| `get_profile_picture` | 获取联系人或群组的个人资料图片网址 |
| `set_contact_name` | 为JID或电话号码设置本地自定义显示名称（在列表和搜索中显示） |
| `sync_contact_names` | 获取WhatsApp个人资料名称并为仍显示为原始JID的聊天存储它们 |
**交互工作流**
| 工具 | 描述 |
|------|-------------|
| `wait_for_message` | 阻塞直到传入消息到达 - 在交互测试中使用，以便AI自动检测手机消息而无需用户提示 |
**工具文档**
| 工具 | 描述 |
|------|-------------|
| `get_tool_info` | 获取任何工具的结构化文档（用法，示例，响应格式，错误，相关工具，陷阱） |
---
## 示例用法
```
# 身份验证
Authenticate WhatsApp with +1234567890
# 发送消息（模糊名称匹配）
Send "I'll be 10 minutes late" to John
# 发送照片
Send the file /data/sessions/media/image/photo.jpg to the Engineering group as an image
# 跨所有聊天搜索
Search my WhatsApp messages for "project deadline"
# 获取摘要
Catch me up on today's WhatsApp activity
# 查看对话
Show me the last 20 messages with the Engineering group
# 查找联系人
Search for contacts named "Sarah"
# 从消息下载媒体
Download media from message ID abc123
# 审批工作流
Send an approval request to Sarah: "Deploy v2.1 to production?"
Check approval status for approval_1234567890_abc
```
---
## 项目结构
```
whatsapp-mcp-docker/
├── src/
│ ├── index.ts # 入口点 - stdio传输 + 生命周期
│ ├── server.ts # 服务器工厂 - 连接工具，存储，安全
│ ├── whatsapp/
│ │ ├── client.ts # whatsmeow-node包装器 + 媒体操作
│ │ └── store.ts # SQLite持久性 + FTS5搜索 + 媒体元数据
│ ├── tools/
│ │ ├── auth.ts # disconnect, authenticate
│ │ ├── status.ts # get_connection_status
│ │ ├── messaging.ts # send_message, list_messages, search_messages
│ │ ├── chats.ts # list_chats, search_contacts, catch_up, mark_messages_read, export_chat_data
│ │ ├── media.ts # download_media, send_file
│ │ ├── approvals.ts # request_approval, check_approvals
│ │ ├── groups.ts # create_group, get_group_info, get_joined_groups, get_group_invite_link, join_group, leave_group, update_group_participants, set_group_name, set_group_topic
│ │ ├── reactions.ts # send_reaction, edit_message, delete_message
│ │ ├── contacts.ts # get_user_info, is_on_whatsapp, get_profile_picture, set_contact_name, sync_contact_names
│ │ ├── wait.ts # wait_for_message
│ │ └── tool-info.ts # get_tool_info + 分层文档助手
│ ├── security/
│ │ ├── audit.ts # SQLite审计日志
│ │ ├── crypto.ts # AES-256-GCM字段级加密
│ │ ├── file-guard.ts # 路径限制，扩展名阻止，魔术字节验证，配额
│ │ └── permissions.ts # 白名单，速率限制，工具禁用，身份验证节流
│ └── utils/
│ ├── fuzzy-match.ts # Levenshtein + 子字符串匹配
│ └── phone.ts # E.164验证 + JID转换
├── docs/
│ ├── README.md # 文档索引
│ ├── API.md # 完整的MCP工具API参考（所有34种工具）
│ ├── TROUBLESHOOTING.md # 症状→原因→修复指南
│ ├── architecture/
│ │ └── OVERVIEW.md # 架构概述
│ ├── guides/
│ │ ├── DEVELOPER.md # 构建，测试，部署程序
│ │ └── ERRORS.md # 错误分类和恢复
│ ├── testing/
│ │ └── TESTING.md # 测试策略，结构和命令
│ └── bugs/ # 错误报告和修复
├── scripts/
│ ├── diagnostics.js # 健康检查和诊断脚本
│ ├── cleanup.ps1 # 完整的拆除脚本（Windows - git-ignored）
│ ├── cleanup.sh # 完整的拆除脚本（Linux/macOS - git-ignored）
│ ├── test.ps1 # 测试运行器（Windows）
│ └── test.sh # 测试运行器（Linux/macOS）
├── examples/
│ └── client-configs.md # 手动MCP客户端配置代码段（Cursor，Claude，VS Code，Gemini，Goose，Cline）
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ └── feature_request.md
│ └── workflows/
│ └── security-audit.yml
├── test/
│ ├── unit/ # 单元测试（node:test）
│ ├── integration/ # MCP协议测试（模拟WhatsApp客户端）
│ └── e2e/ # 现场会话测试（持久身份验证）
├── Dockerfile # 4阶段（prod-deps → 构建者 → 测试 → 运行时），〜80 MB运行时
├── docker-compose.yml # 主容器 + 测试容器（Compose配置文件）
├── whatsapp-mcp-docker-server.yaml # Docker MCP工具包服务器定义
├── recommended-config.yaml # 参考配置值用于docker mcp配置文件
├── .env.example # 环境变量模板（docker-compose回退）
├── package.json
├── package-lock.json
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── PRIVACY.md
```
---
## 安全
- **非root用户**（UID 1001，所有功能都已删除）
- **只读根文件系统**（仅`/data`卷和`/tmp`tmpfs可写）
- **TLS传输** - 直接WhatsApp协议（whatsmeow-node），无需浏览器自动化或TLS绕过
- **静止加密** - 对敏感数据库字段使用AES-256-GCM（`DATA_ENCRYPTION_KEY`）
- **操作系统密钥链中的密钥** - 加密密钥通过`docker mcp secret set`存储，从不存储在配置文件中
- **自动清除** - 消息和媒体在保留期后自动删除（`MESSAGE_RETENTION_DAYS`）
- **文件安全** - 上传路径限制，扩展名阻止，魔术字节验证，512 MB媒体配额
- **联系人白名单** - 限制可以接收消息的联系人（`ALLOWED_CONTACTS`）
- **速率限制** - 传出消息，媒体下载和身份验证尝试
- **输入验证** - Zod模式对所有工具参数的最大长度限制
- **审计跟踪** - 所有工具调用记录到SQLite并带有时间戳
参见[SECURITY.md](./SECURITY.md)以获取完整的安全策略和漏洞报告。
---
## 配置
配置通过Docker MCP工具包（优先）或`docker-compose.yml`环境变量进行管理。
### Docker MCP工具包（优先）
设置和密钥通过Docker Desktop UI或CLI进行管理：
**推荐的初始设置**（在首次部署时运行所有命令）：
```bash
# 1. 设置加密密钥（存储在OS密钥链中）
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | \
docker mcp secret set whatsapp-mcp-docker.data_encryption_key
# 2. 将完整的推荐配置应用于您的配置文件
# 将<your-profile>替换为您的配置文件名称（例如，default-with-portainer）
docker mcp profile config <your-profile> \
--set whatsapp-mcp-docker.rate_limit_per_min=60 \
--set whatsapp-mcp-docker.message_retention_days=90 \
--set whatsapp-mcp-docker.send_read_receipts=true \
--set whatsapp-mcp-docker.auto_read_receipts=true \
--set whatsapp-mcp-docker.presence_mode=available \
--set whatsapp-mcp-docker.welcome_group_name=WhatsAppMCP \
--set whatsapp-mcp-docker.auth_wait_for_link=false \
--set whatsapp-mcp-docker.auth_link_timeout_sec=120 \
--set whatsapp-mcp-docker.auth_poll_interval_sec=5
```
或通过Docker Desktop：**MCP工具包 → WhatsApp MCP → 配置/密钥**。
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `TZ` | 容器时区 - 影响日志时间戳和基于时间的特性（例如`catch_up`的“今日”窗口）。使用IANA名称：`America/Toronto`，`Europe/Paris`，`Asia/Tokyo`。在[维基百科](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)上查看完整列表。 | `UTC` |
| `STORE_PATH` | 会话 + 消息数据库目录 | `/data/sessions` |
| `AUDIT_DB_PATH` | 审计日志数据库路径 | `/data/audit/audit.db` |
| `RATE_LIMIT_PER_MIN` | 每分钟最大发送消息数 | `60` |
| `DOWNLOAD_RATE_LIMIT_PER_MIN` | 每分钟最大媒体下载数 | `30` |
| `DATA_ENCRYPTION_KEY` | AES-256-GCM字段加密的密钥串 | *(通过`docker mcp secret set`设置)* |
| `MESSAGE_RETENTION_DAYS` | 自动删除旧于N天的消息/媒体（0 = 永久保留） | `90` |
| `ALLOWED_CONTACTS` | 以逗号分隔的E.164电话号码白名单（空字符串 = 允许所有） | `""` |
| `DISABLED_TOOLS` | 以逗号分隔的禁用工具列表 | `""` |
| `SEND_READ_RECEIPTS` | 调用`mark_messages_read`时发送实际的阅读回执到WhatsApp（蓝色双勾） | `true` |
| `AUTO_READ_RECEIPTS` | 接收消息时自动标记为已读（发送者立即看到蓝色勾） | `true` |
| `PRESENCE_MODE` | 在线状态：`available`或`unavailable` | `available` |
| `WELCOME_GROUP_NAME` | WhatsApp创建的群组名称（空字符串 = 禁用） | `WhatsAppMCP` |
| `AUTH_WAIT_FOR_LINK` | 默认：`authenticate`显示代码/二维码后等待并轮询，直到链接（`false` = 立即返回；推荐大多数客户端避免工具调用超时） | `false` |
| `AUTH_LINK_TIMEOUT_SEC` | 等待时等待链接的最大秒数（15–600） | `120` |
| `AUTH_POLL_INTERVAL_SEC` | 连接检查之间的默认秒数（2–60） | `5` |
### 变量详情
**`DATA_ENCRYPTION_KEY`** - 使用AES-256-GCM加密敏感字段（消息正文，发送者名称，媒体元数据，审批详细信息）。通过`docker mcp secret set whatsapp-mcp-docker.data_encryption_key`（OS Keychain）或在`.env`中docker-compose使用。生成强密钥：`node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"`。如果丢失密钥，加密数据变得无法恢复。运行没有此密钥是不安全的模式，仅应在明确的操作员覆盖并记录风险接受的情况下进行。
**`MESSAGE_RETENTION_DAYS`** - 在启动时和每小时运行。删除旧于配置的天数的消息，关联的媒体文件和过期的审批。设置为`0`以禁用。
**`RATE_LIMIT_PER_MIN`** - 适用于发送消息（`send_message`，`send_file`）。默认值为60（1/sec持续），舒适的人工智能对话舒适。
**`DOWNLOAD_RATE_LIMIT_PER_MIN`** - 适用于媒体下载（`download_media`）。默认值为30/min。身份验证尝试单独限制为5每30分钟，并带有指数退落。
**`ALLOWED_CONTACTS`** - 以逗号分隔的E.164电话号码（例如`+15145551234,+353871234567`). 设置后，仅这些联系人可以接收消息。
**`DISABLED_TOOLS`** - 以逗号分隔的工具名称列表（例如`send_file,download_media`). 禁用工具调用时返回错误。
**`SEND_READ_RECEIPTS`** - 当`true`，调用`mark_messages_read`发送实际的阅读回执到WhatsApp（蓝色双勾），除了更新本地数据库。设置为`false`仅更新本地数据库。
**`AUTO_READ_RECEIPTS`** - 当`true`，传入消息自动标记为已读（发送者立即看到蓝色勾）。由于服务器是自动化代理，此项默认启用。设置为`false`以控制手动验证。
**PRESENCE_MODE` - 控制在线/离线状态。设置为`available`（默认），设备显示在线并且发送灰色双勾）。设置为`unavailable`以显示离线。
**`WELCOME_GROUP_NAME`** - 首次连接时，`authenticate`显示欢迎消息。设置为一个空字符串以禁用。
**`AUTO_CONNECT_ON_STARTUP`** - 当为`true`（默认）时，如果存在有效的会话，服务器在容器启动时自动重新连接到WhatsApp，而无需调用`authenticate`。设置为`false`以手动启动时连接。**注意：**此变量未在Docker MCP工具包配置文件模式中公开，因此无法通过Docker Desktop UI或`docker mcp profile config`进行设置。仅在`.env`或`docker-compose.yml`中的`environment:`块中设置。
**`AUTH_WAIT_FOR_LINK`**，**`AUTH_LINK_TIMEOUT_SEC`**，**`AUTH_POLL_INTERVAL_SEC`** - `authenticate`工具的默认设置（如果客户端省略`waitForLink`，`linkTimeoutSec`或`pollIntervalSec`）。在Docker MCP工具包中，它们由配置文件`whatsapp-mcp-docker.auth_wait_for_link`，`auth_link_timeout_sec`和`auth_poll_interval_sec`驱动。工具参数始终覆盖这些参数。
**`DEBUG`** - 设置为`true`时，发出详细的诊断输出到stderr。用于诊断连接或协议问题时很有用。永久不要保持开启状态。
---
## 数据持久性
Docker MCP工具包自动为会话持久性提供命名卷：
| 数据 | 卷 | 挂载 | 描述 |
|------|--------|-------|-------------|
| 会话 + 消息 | `whatsapp-sessions` | `/data/sessions` | WhatsApp会话数据库，消息数据库，已下载的媒体 |
| 审计 | `whatsapp-audit` | `/data/audit` | 审计日志SQLite数据库 |
会话数据在容器重启时存活。使用`docker volume rm whatsapp-sessions whatsapp-audit`删除所有数据。
---
## 数据管理
### 备份您的数据
**备份WhatsApp会话和消息：**
bash/zsh：
```bash
mkdir -p whatsapp-backup
docker run --rm \
-v whatsapp-sessions:/data \
-v $(pwd)/whatsapp-backup:/backup \
alpine tar czf /backup/sessions-$(date +%Y%m%d).tar.gz /data
# 备份审计卷（可选）
docker run --rm \
-v whatsapp-audit:/data \
-v $(pwd)/whatsapp-backup:/backup \
alpine tar czf /backup/audit-$(date +%Y%m%d).tar.gz /data
```
PowerShell：
```powershell
New-Item -ItemType Directory -Force -Path whatsapp-backup
$date = Get-Date -Format "yyyyMMdd"
docker run --rm `
-v whatsapp-sessions:/data `
-v "${PWD}\whatsapp-backup:/backup" `
alpine tar czf /backup/sessions-$date.tar.gz /data
```
# 备份审计日志（可选）
```bash
docker run --rm `
-v whatsapp-audit:/data `
-v "${PWD}\whatsapp-backup:/backup" `
alpine tar czf /backup/audit-$date.tar.gz /data
```
**备份加密密钥：**
```bash
# 如果使用docker mcp secrets，请手动从OS Keychain导出
# 在macOS上：security find-generic-password -s "docker-mcp" -a "whatsapp-mcp-docker.data_encryption_key" -w
# 在Windows上：存储在Windows Credential Manager中（搜索“docker/mcp/whatsapp-mcp-docker”）
# 在Linux上：存储在secret-service（GNOME Keyring或KWallet）中
# 保存到密码管理器 - 不要提交到git！
```
### 从备份恢复
bash/zsh:
```bash
docker compose down
docker run --rm \
-v whatsapp-sessions:/data \
-v $(pwd)/whatsapp-backup:/backup \
alpine tar xzf /backup/sessions-20260331.tar.gz -C /
docker compose up -d
```
PowerShell:
```powershell
docker compose down
docker run --rm `
-v whatsapp-sessions:/data `
-v "${PWD}\whatsapp-backup:/backup" `
alpine tar xzf /backup/sessions-20260331.tar.gz -C /
docker compose up -d
```
### 迁移到新主机
```bash
# 在旧主机上：创建备份（参见上文）
# 将备份文件复制到新主机（scp、rsync等）
# 在新主机上：
# 1. 安装Docker Desktop并启用MCP Toolkit
# 2. 恢复卷（参见上文）
# 3. 设置加密密钥
docker mcp secret set whatsapp-mcp-docker.data_encryption_key
# 4. 注册目录并添加到配置文件
# 5. 启动容器 - 会话应自动恢复
```
### 删除所有数据
```bash
# 停止容器并删除卷
docker compose down -v
# 验证卷是否已删除（bash/zsh）
docker volume ls | grep whatsapp
# 验证卷是否已删除（PowerShell）
docker volume ls | findstr whatsapp
# 两者均应返回空结果
```
> **警告：** 这将永久删除所有WhatsApp会话、消息和审计日志。您需要重新认证。
---
## 技术栈
| 类别 | 技术 |
|----------|-----------|
| **运行时** | Node.js 22（Alpine） |
| **WhatsApp协议** | whatsmeow-node（Go二进制文件） |
| **MCP SDK** | @modelcontextprotocol/sdk |
| **数据库** | SQLite（better-sqlite3）与FTS5 |
| **二维码** | qrcode（容器内PNG生成） |
| **验证** | Zod |
| **容器** | Docker（4阶段，~80 MB运行时） |
| **编排** | Docker MCP Toolkit + MCP Gateway |
---
## 文档
- [docs/API.md](./docs/API.md) — 完整的MCP工具API参考（所有34种工具）
- [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) — 症状→原因→解决方法指南
- [docs/guides/DEVELOPER.md](./docs/guides/DEVELOPER.md) — 构建、测试和部署流程
- [docs/architecture/OVERVIEW.md](./docs/architecture/OVERVIEW.md) — 架构概述
- [docs/guides/ERRORS.md](./docs/guides/ERRORS.md) — 错误分类和恢复
- [docs/testing/TESTING.md](./docs/testing/TESTING.md) — 测试策略和命令
- [examples/client-configs.md](./examples/client-configs.md) — 手动MCP客户端配置代码段（Cursor、Claude、VS Code、Gemini、Goose、Cline、直接Compose）
- [recommended-config.yaml](./recommended-config.yaml) — `docker mcp profile config`的参考配置值
- [CHANGELOG.md](./CHANGELOG.md) — 发布历史
- [PRIVACY.md](./PRIVACY.md) — 隐私政策和数据处理
- [SECURITY.md](./SECURITY.md) — 安全政策和漏洞报告
- [CONTRIBUTING.md](./CONTRIBUTING.md) — 贡献指南
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) — 社区标准
---
## 常见问题和故障排除
### ⚠️ 认证问题
**问题：** 配对代码返回400错误
- **原因：** WhatsApp限制配对尝试（每30分钟5次）
- **解决方案：** 等待10-15分钟，然后重试。服务器会自动切换到二维码。
**问题：** 二维码已过期
- **原因：** 二维码在~20秒后过期
- **解决方案：** 再次调用`authenticate`以获取新的二维码
- **预防：** 在调用`authenticate`之前，确保WhatsApp已打开并准备好。
**问题：** “已认证”但消息未发送
- **原因：** 会话可能已过期（20天不活动）或WhatsApp断开连接
- **解决方案：**
1. 检查状态：`docker compose logs --tail 50 whatsapp-mcp-docker`
2. 查找“logged_out”或“session expired”消息
3. 再次调用`authenticate`以重新链接
**问题：** 无法及时扫描二维码
- **原因：** 二维码过期快，您需要浏览WhatsApp菜单
- **解决方案：**
1. 打开WhatsApp → 设置 → 链接设备 **在调用`authenticate`之前**
2. 点击“链接设备”并准备好摄像头
3. 然后调用`authenticate`以生成二维码
- **替代方案：** 使用配对代码（有效期60秒）
### ⚠️ 速率限制
**问题：** 消息的“速率限制已超过”
- **默认：** 每分钟60条消息
- **解决方案：** 等待窗口重置或调整`RATE_LIMIT_PER_MIN`
- **警告：** 发送太多消息太快可能会导致您的WhatsApp账户被封禁。
**问题：** “身份验证冷却期激活”
- **原因：** 身份验证尝试失败会触发指数退火（60秒 → 120秒 → 240秒 → 480秒 → 900秒）
- **解决方案：** 等待冷却期过期
- **预防：** 在调用`authenticate`之前，确保电话号码正确。
### ⚠️ 会话和数据问题
**问题：** 容器重启后会话丢失
- **原因：** Docker卷未持续存在
- **检查：** `docker volume ls | grep whatsapp-sessions`
- **解决方案：** 确保`whatsapp-sessions`卷存在并已挂载
**问题：** 消息未出现在搜索结果中
- **原因：** FTS5索引可能不同步或消息缺少正文
- **解决方案：**
1. 检查消息是否存在：使用`list_messages`获取聊天记录
2. 验证搜索查询：尝试更简单的关键词
3. FTS5限制：媒体消息（无文本）不可搜索
**问题：** 媒体下载失败
- **原因1：** 媒体在WhatsApp服务器上已过期（30天限制）
- **原因2：** 消息ID无效或早于元数据跟踪
- **解决方案：** 在接收后尽快下载媒体；旧媒体可能不可用
### ⚠️ 联系人和名称解析
**问题：** 模糊搜索匹配错误的联系人
- **原因：** 多个联系人具有相似的名称
- **解决方案：** 使用确切的JID而不是名称：`send_message({ to: "1234567890@s.whatsapp.net", ... })`
- **预防：** 首先使用`search_contacts`查找确切的JID
**问题：** 联系人名称显示为电话号码
- **原因：** WhatsApp的名称解析可能需要时间或失败
- **解决方案：** 名称异步解析；等待消息到达
- **注意：** 这是纯粹的视觉效果；使用JID仍然可以正常发送消息
### ⚠️ 备份和恢复
**问题：** 需要备份/恢复会话
- **备份（bash/zsh）：**
```bash
docker run --rm -v whatsapp-sessions:/data -v $(pwd):/backup alpine \
tar czf /backup/whatsapp-backup.tar.gz /data
```
- **备份（PowerShell）：**
```powershell
docker run --rm -v whatsapp-sessions:/data -v "${PWD}:/backup" alpine `
tar czf /backup/whatsapp-backup.tar.gz /data
```
- **恢复（bash/zsh）：**
```bash
docker run --rm -v whatsapp-sessions:/data -v $(pwd):/backup alpine \
tar xzf /backup/whatsapp-backup.tar.gz -C /data --strip-components 1
```
- **恢复（PowerShell）：**
```powershell
docker run --rm -v whatsapp-sessions:/data -v "${PWD}:/backup" alpine `
tar xzf /backup/whatsapp-backup.tar.gz -C /data --strip-components 1
```
### 📞 获取帮助
如果问题仍然存在：
1. **检查日志：** `docker compose logs --tail 100 whatsapp-mcp-docker`
2. **运行诊断：** `node scripts/diagnostics.js --verbose`
3. **搜索问题：** [GitHub Issues](https://github.com/Malaccamaxgit/whatsapp-mcp-docker/issues)
4. **报告错误：** 包括日志、Docker版本和重现步骤
---
## 测试
测试在Docker容器中通过`tester-container`运行 - 不需要本地构建工具。`npm test`脚本在主机上故意被阻止；请改用容器的默认CMD。
```bash
# 构建测试镜像（tester-container位于“test”Compose配置文件后）
docker compose --profile test build tester-container
# 运行所有单元测试和集成测试（使用容器默认CMD）
docker compose --profile test run --rm tester-container
# 运行特定的测试文件
docker compose --profile test run --rm tester-container npx tsx --test test/unit/crypto.test.ts
# e2e测试的身份验证
docker compose --profile test run --rm tester-container npx tsx test/e2e/setup-auth.ts
# 使用实时会话运行e2e测试
docker compose --profile test run --rm tester-container npx tsx --test test/e2e/live.test.ts
```
| 层 | 涵盖内容 |
|-------|----------------|
| **单元测试** | phone、fuzzy-match、crypto、file-guard、permissions、audit、store、reconnect、receipts |
| **集成测试** | 完整的MCP协议往返测试，模拟WhatsApp客户端 |
| **端到端测试** | 实时WhatsApp会话（只读，需要身份验证） |
参见 [docs/guides/DEVELOPER.md](./docs/guides/DEVELOPER.md) 以获取完整的测试指南。
---
## 故障排除
### 🔍 诊断命令
运行诊断脚本以检查系统健康状况：
> **需要主机上的Node.js。** 如果您在主机上没有安装Node.js，请改用手动诊断 - 服务器本身在Docker中运行Node，无需主机安装即可正常使用。
```bash
# 快速状态检查
node scripts/diagnostics.js
# 详细输出，包含完整日志
node scripts/diagnostics.js --verbose
# JSON输出，用于自动化
node scripts/diagnostics.js --json
```
**手动诊断：**
```bash
# 检查容器是否正在运行
docker compose ps
# 查看最后50行日志
docker compose logs --tail 50 whatsapp-mcp-docker
# 检查卷是否存在（bash/zsh）
docker volume ls | grep whatsapp
# 检查卷是否存在（PowerShell）
docker volume ls | findstr whatsapp
# 验证加密密钥已设置（bash/zsh）
docker mcp secret ls | grep whatsapp-mcp-docker
# 验证加密密钥已设置（PowerShell）
docker mcp secret ls | findstr whatsapp-mcp-docker
# 检查目录注册
docker mcp catalog ls
# 列出所有服务器，跨所有配置文件
docker mcp profile server ls
# 列出特定配置文件的服务器（--profile标志不存在；使用--filter）
docker mcp profile server ls --filter profile=<your-profile>
# 测试WhatsApp连接状态（来自MCP客户端）
get_connection_status
```
---
### 常见问题和解决方案
#### 1. 身份验证问题
**问题：** 配对代码返回400错误或过期
**原因：** WhatsApp限制配对尝试或代码在60秒内过期
**解决方案：**
- 如果速率限制，请等待10-15分钟
- 在调用`authenticate`之前，确保WhatsApp移动应用已准备就绪
- 如果配对代码失败，服务器会自动切换到二维码
- 二维码在~20秒后过期 - 请求新的二维码如果已过期
**预防：** 在调用`authenticate`之前，打开WhatsApp → 设置 → 链接设备 → “链接设备”，以便您立即输入代码。传递`waitForLink: true`，如果您希望工具轮询直到链接（注意：这可能会超过某些MCP客户端的工具调用超时 - 参见`auth_wait_for_link`配置）。
---
**问题：** “已认证”但消息未发送
**原因：** 会话可能已过期或WhatsApp断开连接
**解决方案：**
```bash
# 检查连接状态
get_connection_status
# 如果断开连接，请检查注销原因
# 如果原因是“revoked”、“banned”或“unlinked” → 重新认证
authenticate({ phoneNumber: "+1234567890" })
```
---
#### 2. 会话过期
**问题：** WhatsApp不连接，活动后~20天
**原因：** WhatsApp链接设备会话在~20天不活动后过期
**解决方案：**
1. 再次调用`authenticate`，使用相同的电话号码
2. 会话将恢复（如果仍在20天内，则无需重新链接）
3. 如果已过期，您需要重新链接配对代码或二维码
**预防：** 至少每2周发送一次消息或使用服务器。
---
#### 3. 速率限制
**问题：** “速率限制已超过（每分钟60条消息）”
**原因：** WhatsApp可能会因快速发送太多消息而封禁账户
**解决方案：**
- 等待60秒，让速率限制重置
- 减少消息频率
- 仅当您有合法的高容量使用需求时，才增加`RATE_LIMIT_PER_MIN`
**警告：** 过度发送消息可能会导致您的WhatsApp账户被封禁。
---
**问题：** “太多身份验证尝试（每30分钟5次）”
**原因：** 身份验证尝试次数有限，每30分钟5次
**解决方案：**
- 等待冷却期（指数退火：60秒 → 120秒 → 240秒 → 480秒 → 900秒）
- 在身份验证尝试失败后不要立即重试
- 如果配对代码失败，请等待二维码备用
---
#### 4. 联系人解析问题
**问题：** “无法解析收件人”或联系人匹配错误
**原因：** 模糊匹配找到多个候选者或没有匹配
**解决方案：**
```bash
# 从list_chats获取确切的JID
list_chats()
# 直接使用JID（绕过模糊匹配）
send_message({ to: "1234567890@c.us", message: "Hello" })
```
**提示：** 联系人名称可能不会立即解析消息 - 等待几秒钟以进行名称解析。
---
#### 5. 媒体下载失败
**问题：** “此消息无媒体元数据”
**原因：** 媒体在WhatsApp服务器上已过期，或媒体在启用元数据跟踪之前收到
**解决方案：**
- WhatsApp服务器上的媒体在30天后过期
- 仅在启用服务器后才能下载收到的媒体
- 检查`list_messages`中的`has_media`标志，查看媒体是否可用
---
**问题：** “媒体存储配额已超过”
**原因：** 媒体目录总量达到512 MB限制
**解决方案：**
```bash
# 检查媒体目录大小
docker compose exec whatsapp-mcp-docker du -sh /data/sessions/media
# 手动删除旧媒体文件或等待自动清除
# 自动清除如果MESSAGE_RETENTION_DAYS > 0，则每小时运行一次
```
---
#### 6. 搜索结果为空
**问题：** `search_messages`找不到任何结果
**原因：**
- FTS5索引可能未跟上（延迟索引）
- 消息已加密，但搜索索引包含纯文本
- 查询语法错误（布尔运算符需要大写）
**解决方案：**
```bash
# 尝试不带运算符的简单查询
search_messages({ query: "hello" }) # 而不是 "hello AND world"
# 使用引号进行精确短语搜索
search_messages({ query: "\"exact phrase\"" })
# 检查消息是否存在
list_messages({ chat: "联系人姓名", limit: 10 })
```
---
#### 7. 容器问题
**问题：** 容器无法启动
**解决方案：**
```bash
# 检查日志
docker compose logs whatsapp-mcp-docker
# 验证卷存在
docker volume ls | grep whatsapp
# 重建镜像
docker compose build --no-cache
# 删除并重新创建
docker compose down -v
docker compose up -d
```
---
**问题：** 高内存使用率
**原因：** 消息历史同步加载许多消息到内存中
**解决方案：**
- 设置`MESSAGE_RETENTION_DAYS`以限制存储的消息
- 在`list_messages`中使用分页（limit: 50, page: 0, 1, 2...）
- 定期重启容器以清除内存
---
### 身份验证失败
如果配对代码返回400错误，服务器会自动切换到二维码身份验证 - 二维码直接在工具响应中作为图像和数据URI返回（将URI粘贴到任何浏览器中即可查看）。检查容器日志以获取详细信息：`docker compose logs whatsapp-mcp-docker`。
### 速率限制（429）
WhatsApp限制配对尝试。等待10-15分钟后重试。
### 会话过期
WhatsApp会话在~20天不活动后过期。服务器自动检测到这一点：它发送一个`notifications/disconnected` MCP通知到您的客户端，在过时会话文件中进行清理，并在`get_connection_status`中报告原因。自动重试5次，指数退火后停止。启动时每5秒重试一次，健康心跳检测到静默连接断开。60秒
---
## 许可
Apache License 2.0 — 参见 [LICENSE](./LICENSE) 获取详细信息。
---
## 免责声明
本项目不隶属于WhatsApp或Meta。WhatsApp不官方支持非官方API客户端。请自担风险，并遵守WhatsApp的服务条款。
---
## 联系方式
- **AI作者：** Qwen3-Coder-Next • MiniMax-M2.7 • Qwen3.5 • Nemotron-3-Super
- **总监：** Benjamin Alloul — [Benjamin.Alloul@gmail.com](mailto:Benjamin.Alloul@gmail.com)
- **问题：** [GitHub Issues](https://github.com/Malaccamaxgit/whatsapp-mcp-docker/issues)
- **讨论：** [GitHub Discussions](https://github.com/Malaccamaxgit/whatsapp-mcp-docker/discussions)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器