Whatsapp MCP Docker

WhatsApp MCP服务器

人工智能代理的WhatsApp集成 --通过任何MCP客户端发送消息、搜索聊天、共享媒体、审批工作流和智能活动摘要。设计为通过以下方式作为容器化MCP服务器运行 .

致谢： 作者非常清楚 我要跳了！，它提供了一个更强大、功能更完整的WhatsApp集成解决方案。这个项目是当一个有着太多好奇心、良好的系统设计直觉和现代人工智能帮助的业余程序员决定看看他们能在多大程度上推进他们的周末项目时发生的事情。这是一个关于MCP服务器、容器化和WhatsApp协议集成的学习练习——几年前单独尝试这种事情是不合理的，但现在由于更好的工具和人工智能的大量帮助，它已经触手可及。

 ](https://nodejs.org/)   ](https://docs.docker.com/ai/mcp-catalog-and-toolkit/)

注： 该项目需要 随着 MCP工具包 启用。或者，您可以使用Docker引擎+Docker Compose运行它（不使用MCP网关功能）。

______________________________________________________________________

为什么选择Docker MCP工具包？

此服务器运行在Docker容器中，由 ，而不是直接在您的主机上。

______________________________________________________________________

特性

• 34 MCP工具 --完整的WhatsApp控制：消息传递、媒体、搜索、联系人、组、消息操作、批准、状态、实时交互、会话管理和分层工具文档
• 模糊名称匹配 --说“约翰”或“读书俱乐部”，服务器就会通过Levenshtein距离找到合适的聊天对象
• 媒体支持 --下载收到的媒体并发送图像、视频、音频和文档
• 全文检索 --SQLite FTS5使用关键字、短语和布尔运算符对所有消息进行索引
• 智能追赶 --一个总结当前聊天记录、未决问题和未读亮点的工具
• 审批流程 --通过WhatsApp发送批准请求；收件人回复“批准”或“拒绝”
• 配对代码验证 --基于文本的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 ```

# 0. Find your profile name (Docker Desktop creates "default" on install)
docker mcp profile list

# 1. Download the server definition file (no full clone needed)
curl -O https://raw.githubusercontent.com/Malaccamaxgit/whatsapp-mcp-docker/main/whatsapp-mcp-docker-server.yaml

# 2. Create catalog (one-time setup)
docker mcp catalog create my-mcp --title "My MCP Servers" \
  --server file://./whatsapp-mcp-docker-server.yaml

# 3. Add to your profile (replace "default" with your profile name from step 0)
docker mcp profile server add default \
  --server file://./whatsapp-mcp-docker-server.yaml

# 4. Connect your MCP client (replace "cursor" with your client — see table below)
docker mcp client connect cursor --profile default

# 5. Restart / reload your MCP client so it picks up the new tools

# 6. In your client, say: "Authenticate WhatsApp with +1234567890"

步骤4支持的客户端： cursor, claude-code, claude-desktop, vscode, gemini, goose，以及 更多.快跑 docker mcp client connect --help 查看完整列表。

就是这样！ 您现在已连接到WhatsApp。图片(malaccamax/whatsapp-mcp-docker:latest)首次使用时会自动从Docker Hub中提取——不需要构建步骤。

注： 连接后，您必须在WhatsApp工具出现之前重新启动或重新加载MCP客户端（有关客户端特定的说明，请参阅下面完整设置中的步骤5）。跑步 docker mcp tools ls 在终端中只显示了8个MCP Toolkit元工具——在网关首次使用时启动容器后，34个WhatsApp工具出现在您的客户端中。 重要提示： 在某些MCP会话中，您可能需要在工具可用之前明确激活配置文件。如果你得到 Error: Tool 'get_connection_status' not found in current session，运行： ``bash docker mcp profile activate ` 或者在MCP客户端会话中，使用 mcp-activate-profile` 元工具。这是Docker MCP网关自动加载行为中的一个已知差距。

下一步： 设置加密和推荐配置（如下）以确保安全使用。

______________________________________________________________________

📋 完整设置（推荐的安全配置）

0.查找您的个人资料名称

Docker Desktop创建了一个名为 default 安装时。在继续之前检查您的：

docker mcp profile list

在任何地方使用此处显示的名称 `` 出现在下面的步骤中。

需要专门的个人资料吗？ 在Docker桌面中，转到 MCP工具包→ 档案 然后单击 + 要创建一个，请使用该名称。

1.获得项目

选项A——只使用服务器YAML（建议大多数用户使用）：

镜像会自动从Docker Hub中提取。您只需要服务器定义文件：

curl -O https://raw.githubusercontent.com/Malaccamaxgit/whatsapp-mcp-docker/main/whatsapp-mcp-docker-server.yaml

选项B——完全克隆+本地构建（适用于开发人员或自托管）：

如果你想修改源代码或在没有Docker Hub的情况下运行，请在本地克隆和构建：

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://./ catalog和profile命令中的路径是相对于您的工作目录的。

2.设置加密密钥

设置加密密钥 （存储在操作系统钥匙串中--否 .env 所需文件）：

# Option A: Using Node.js (if installed on host) — bash/zsh only
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | docker mcp secret set whatsapp-mcp-docker.data_encryption_key

# Option B: Using Docker (no Node.js required on host) — bash/zsh only
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用户： 管道(|)并重定向( `powershell # Option A: Using Python (recommended — avoids require() escaping issues) $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" # Option B: Using Node.js — requires careful quoting; base64 chars + / = may cause issues $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" ` 如果您看到“登录会话不存在”错误，但密钥仍显示在 docker mcp secret ls，密钥已成功存储在 docker-pass` 后端——该错误是来自辅助Windows凭据管理器后端的误导性警告，可以安全地忽略。

验证密钥是否已存储 (docker mcp secret set 未确认成功）：

# bash/zsh
docker mcp secret ls | grep whatsapp
# PowerShell
docker mcp secret ls | findstr whatsapp

您应该看到一行包含 whatsapp-mcp-docker.data_enc….

提示： 确保生成的密钥安全！如果丢失，加密邮件将无法恢复。将其备份到密码管理器。 安全态势： 跑步没有 DATA_ENCRYPTION_KEY 这是一种不安全的模式。只有在明确的操作员覆盖和记录的风险接受情况下才能做到这一点。

3.创建自定义目录

在中注册服务器 自定义目录 所以它出现在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 ``

docker mcp catalog create my-custom-mcp-servers \
  --title "My Custom MCP Servers" \
  --server file://./whatsapp-mcp-docker-server.yaml

在Docker桌面中，转到 MCP工具包→ 目录 --the WhatsApp MCP 服务器现在出现在您的自定义目录下，其中包含所有34个工具、配置选项和机密。

提示： 要在代码更改后更新目录，请重新运行相同的命令——它将替换现有条目。若要稍后添加更多服务器，请使用多个 --server 旗帜。

4.添加到配置文件并应用配置

将服务器添加到配置文件中，以便MCP客户端可以使用它。

选项A--从目录UI：

1. 在 MCP工具包→ 目录，查找 WhatsApp MCP 在您的定制目录下。
2. 选中服务器卡上的复选框。
3. 从下拉列表中选择一个配置文件并确认。

选项B--CLI：

docker mcp profile server add  \
  --server file://./whatsapp-mcp-docker-server.yaml

选项C——Docker桌面配置文件选项卡：

1. 打开Docker桌面并转到 MCP工具包→ 档案.
2. 选择现有配置文件（或创建新配置文件）。
3. 在 服务器 部分，单击 + 并添加服务器。

所有选项都将服务器注册到 longLived: true （持久容器）， secrets （来自OS Keychain的加密密钥）和所有34个工具。

添加后，应用推荐的配置：

PowerShell用户： 使用回溯(` `)而不是反斜杠(\)用于线路延续。 `powershell docker mcp profile config --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 mcp profile config  \
  --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桌面进行配置： 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客户端连接到配置文件，替换您的客户端名称：

docker mcp client connect  --profile 

支持的客户端名称： cursor, claude-code, claude-desktop, vscode, gemini, goose，以及 其他.快跑 docker mcp client connect --help 查看完整列表。

这会自动将MCP网关条目写入客户端的配置文件。 连接后，重新启动或重新加载您的客户端，使其能够启动新服务器：

为什么不 docker mcp tools ls 展示我的34个工具？ 该命令仅显示8个MCP工具包元工具（例如。 mcp-add, mcp-find).网关启动后，您的MCP客户端中会出现34个WhatsApp工具 whatsapp-mcp-docker 容器在第一次工具调用时。从终端看不到它们。

连接 手动地 相反，将MCP网关条目直接添加到客户端的配置文件中。每个受支持客户端的现成代码片段都在 examples/client-configs.md。每个客户端将其配置存储在不同的位置——有关确切路径，请参阅客户端的文档。输入格式为：

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", ""]
    }
  }
}

Windows用户： 这 docker mcp client connect 命令自动注入所需的Windows环境变量(LOCALAPPDATA, ProgramData, ProgramFiles).如果手动编辑配置文件，则必须自己添加，否则网关无法找到凭据： ``json { "mcpServers": { "MCP_DOCKER": { "command": "docker", "args": ["mcp", "gateway", "run", "--profile", ""], "env": { "LOCALAPPDATA": "C:\\Users\\\\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）

身份验证和状态

消息传递

联系人和聊天

媒体

智能

审批流程

组管理

消息操作

联系人和用户信息

交互式工作流

工具文档

______________________________________________________________________

示例用法

# Authenticate
Authenticate WhatsApp with +1234567890

# Send a message (fuzzy name matching)
Send "I'll be 10 minutes late" to John

# Send a photo
Send the file /data/sessions/media/image/photo.jpg to the Engineering group as an image

# Search across all chats
Search my WhatsApp messages for "project deadline"

# Get a summary
Catch me up on today's WhatsApp activity

# View a conversation
Show me the last 20 messages with the Engineering group

# Find a contact
Search for contacts named "Sarah"

# Download media from a message
Download media from message ID abc123

# Approval workflow
Send an approval request to Sarah: "Deploy v2.1 to production?"
Check approval status for approval_1234567890_abc

______________________________________________________________________

项目结构

whatsapp-mcp-docker/
├── src/
│   ├── index.ts              # Entry point — stdio transport + lifecycle
│   ├── server.ts             # Server factory — wires tools, store, security
│   ├── whatsapp/
│   │   ├── client.ts         # whatsmeow-node wrapper + media operations
│   │   └── store.ts          # SQLite persistence + FTS5 search + media metadata
│   ├── 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 + layered documentation helpers
│   ├── security/
│   │   ├── audit.ts          # SQLite audit logging
│   │   ├── crypto.ts         # AES-256-GCM field-level encryption
│   │   ├── file-guard.ts     # Path confinement, extension/magic checks, quota
│   │   └── permissions.ts    # Whitelist, rate limiting, tool disabling, auth throttle
│   └── utils/
│       ├── fuzzy-match.ts    # Levenshtein + substring matching
│       └── phone.ts          # E.164 validation + JID conversion
├── docs/
│   ├── README.md             # Documentation index
│   ├── API.md                # Full MCP tool API reference (all 34 tools)
│   ├── TROUBLESHOOTING.md    # Symptom → cause → fix guide
│   ├── architecture/
│   │   └── OVERVIEW.md       # Architecture overview
│   ├── guides/
│   │   ├── DEVELOPER.md      # Build, test, deploy procedures
│   │   └── ERRORS.md         # Error taxonomy and recovery
│   ├── testing/
│   │   └── TESTING.md        # Test strategy, structure, and commands
│   └── bugs/                 # Bug reports and fixes
├── scripts/
│   ├── diagnostics.js        # Health check and diagnostic script
│   ├── cleanup.ps1           # Full teardown script (Windows — git-ignored)
│   ├── cleanup.sh            # Full teardown script (Linux/macOS — git-ignored)
│   ├── test.ps1              # Test runner (Windows)
│   └── test.sh               # Test runner (Linux/macOS)
├── examples/
│   └── client-configs.md     # Manual MCP client config snippets (Cursor, Claude, VS Code, Gemini, Goose, Cline)
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   └── feature_request.md
│   └── workflows/
│       └── security-audit.yml
├── test/
│   ├── unit/                 # Unit tests (node:test)
│   ├── integration/          # MCP protocol tests (mock WhatsApp client)
│   └── e2e/                  # Live session tests (persistent auth)
├── Dockerfile                # 4-stage (prod-deps → builder → test → runtime), ~80 MB runtime
├── docker-compose.yml        # Main + tester-container (Compose profiles)
├── whatsapp-mcp-docker-server.yaml  # Docker MCP Toolkit server definition
├── recommended-config.yaml   # Reference config values for docker mcp profile config
├── .env.example              # Environment variable template (docker-compose fallback)
├── 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协议（whatsmow节点），无浏览器自动化或TLS绕过
• 静态加密 --AES-256-GCM用于敏感数据库字段(DATA_ENCRYPTION_KEY)
• 操作系统钥匙链中的秘密 --通过以下方式存储的加密密钥 docker mcp secret set，从不在配置文件中
• 自动清洗 --邮件和媒体在保留期后自动删除(MESSAGE_RETENTION_DAYS)
• 文件安全性 --上传路径限制、扩展阻止列表、魔术字节验证、512 MB媒体配额
• 联系人白名单 --限制谁可以接收消息(ALLOWED_CONTACTS)
• 速率限制 --出站消息、媒体下载和身份验证尝试
• 输入验证 --所有工具参数都有最大长度限制的Zod模式
• 审计跟踪 --所有工具调用都记录到SQLite中，并带有时间戳

看 安全.md 用于完整的安全策略和漏洞报告。

______________________________________________________________________

配置

配置通过Docker MCP工具包（首选）或 docker-compose.yml 环境变量。

Docker MCP工具包（首选）

设置和机密通过Docker桌面UI或CLI进行管理：

推荐的初始设置 （首次部署时运行所有命令）：

# 1. Set encryption key (stored in OS Keychain)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))" | \
  docker mcp secret set whatsapp-mcp-docker.data_encryption_key

# 2. Apply complete recommended configuration to your profile
# Replace  with your profile name (e.g., default-with-portainer)
docker mcp profile config  \
  --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桌面进行配置： MCP工具包→ WhatsApp MCP→ 配置/秘密.

环境变量

变量详细信息

DATA_ENCRYPTION_KEY --使用AES-256-GCM加密敏感字段（消息正文、发件人姓名、媒体元数据、批准详细信息）。通过存储 docker mcp secret set whatsapp-mcp-docker.data_encryption_key （OS钥匙扣）或 .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/秒），适合AI助手对话。

DOWNLOAD_RATE_LIMIT_PER_MIN --适用于媒体下载(download_media).默认值为30/min。身份验证尝试次数分别限制为每30分钟5次，并采用指数回退。

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，收到的消息会在WhatsApp上自动标记为已读（发件人会立即看到蓝色复选标记）。由于服务器是一个自动代理，因此默认情况下启用了此功能。设置为 false 通过以下方式手动控制读取接收时间 mark_messages_read.

PRESENCE_MODE --控制链接设备的联机/脱机状态。设置为 available （默认），这样设备就会在线显示，并自动发送送货收据（灰色双勾）。设置为 unavailable 离线显示。

WELCOME_GROUP_NAME --在第一次连接时，服务器会创建一个具有此名称的WhatsApp组，并发送一条问候消息。设置为空字符串以禁用。

AUTO_CONNECT_ON_STARTUP --何时 true （默认），如果存在有效会话，服务器将在容器启动时自动重新连接到WhatsApp，而无需调用 authenticate。设置为 false 以断开连接模式启动并手动连接。 注： 此变量未在Docker MCP Toolkit配置文件配置模式中公开，无法通过Docker桌面UI或 docker mcp profile config.通过设置 .env 或 environment: 挡住 docker-compose.yml 只有。

AUTH_WAIT_FOR_LINK, AUTH_LINK_TIMEOUT_SEC, AUTH_POLL_INTERVAL_SEC --默认值 authenticate 客户端省略时的工具 waitForLink, linkTimeoutSec，或 pollIntervalSec。在Docker MCP Toolkit中，它们由配置文件配置驱动 whatsapp-mcp-docker.auth_wait_for_link, auth_link_timeout_sec，以及 auth_poll_interval_sec.Tool参数总是覆盖该调用的这些参数。

DEBUG --当设置为 true，向stderr发出详细的诊断输出。在诊断连接或协议问题时很有用。除非你喜欢阅读堆积如山的文字，否则不要一直开着它。

______________________________________________________________________

数据持久层

Docker MCP Toolkit自动为会话持久性配置命名卷：

会话数据在容器重启后仍然有效。使用 docker volume rm whatsapp-sessions whatsapp-audit 删除所有数据。

______________________________________________________________________

数据管理

备份您的数据

备份WhatsApp会话和消息：

bash/zsh：

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

# Backup audit volume (optional)
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：

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

# Backup audit volume (optional)
docker run --rm `
  -v whatsapp-audit:/data `
  -v "${PWD}\whatsapp-backup:/backup" `
  alpine tar czf /backup/audit-$date.tar.gz /data

备份加密密钥：

# If using docker mcp secrets, export from OS Keychain manually
# On macOS: security find-generic-password -s "docker-mcp" -a "whatsapp-mcp-docker.data_encryption_key" -w
# On Windows: Stored in Windows Credential Manager (search for "docker/mcp/whatsapp-mcp-docker")
# On Linux: Stored in secret-service (GNOME Keyring or KWallet)

# Save to password manager - DO NOT commit to git!

从备份中恢复

bash/zsh：

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：

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

迁移到新主机

# On old host: create backup (see above)
# Copy backup files to new host (scp, rsync, etc.)

# On new host:
# 1. Install Docker Desktop and enable MCP Toolkit
# 2. Restore volumes (see above)
# 3. Set encryption key
docker mcp secret set whatsapp-mcp-docker.data_encryption_key
# 4. Register catalog and add to profile
# 5. Start container - session should resume automatically

删除所有数据

# Stop container and remove volumes
docker compose down -v

# Verify volumes are gone (bash/zsh)
docker volume ls | grep whatsapp
# Verify volumes are gone (PowerShell)
docker volume ls | findstr whatsapp
# Both should return nothing

警告： 这将永久删除所有WhatsApp会话、消息和审核日志。您需要重新验证身份。

______________________________________________________________________

技术栈

______________________________________________________________________

文档

• docs/API.md文件 -完整的MCP工具API参考（全部34个工具）
• docs/TROUBLESHOOTING.md --症状→ 原因→ 固定指南
• 文档/指南/开发者.md --构建、测试和部署过程
• docs/architecture/OVERVIEW.md --架构概述
• docs/guides/ERRORS.md --错误分类和恢复
• 文档/测试/测试.md --测试策略和命令
• examples/client-configs.md --手动MCP客户端配置代码片段（Cursor、Claude、VS Code、Gemini、Goose、Cline、direct Compose）
• 推荐-config.yaml --参考配置值 docker mcp profile config
• 更改日志.md --发布历史
• 隐私.md --隐私政策和数据处理
• 安全.md --安全策略和漏洞报告
• 贡献.md --贡献指南
• 代码_OF_CONDUCT.md --社区标准

______________________________________________________________________

常见陷阱和故障排除

⚠️ 身份验证问题

问题：配对代码返回400错误

• 原因： WhatsApp速率限制配对尝试（每30分钟5次）
• 解决方案： 等待10-15分钟，然后重试。服务器自动回退到二维码。
• 预防： 如果配对代码经常失败，请使用二维码身份验证。

问题：二维码已过期

• 原因： 二维码将在约20秒后过期
• 解决方案： 呼叫 authenticate 再次获取新的二维码
• 预防： 在呼叫验证之前打开WhatsApp并做好准备

问题：“已通过身份验证”，但消息未发送

• 原因： 会话可能已过期（20天不活动）或WhatsApp已断开连接
• 解决方案：

1. 检查状态： docker compose logs --tail 50 whatsapp-mcp-docker 1. 查找“logged_out”或“session expired”消息 1. 呼叫 authenticate 再次重新链接

问题：无法及时扫描二维码

• 原因： 二维码很快过期，您需要浏览WhatsApp菜单
• 解决方案：

1. 打开WhatsApp→ 设置→ 已关联设备 之前 呼叫身份验证 1. 点击“链接设备”并准备好相机 1. 然后打电话 authenticate 生成二维码

• 备选方案： 使用配对码（持续60秒）

⚠️ 速率限制

问题：邮件“超出速率限制”

• 违约： 每分钟60条消息
• 解决方案： 等待车窗重置或调整 RATE_LIMIT_PER_MIN
• 警告： 发送太多消息太快可能会让你的帐户被WhatsApp禁止

问题：“身份验证冷却处于活动状态”

• 原因： 失败的身份验证尝试触发指数回退（60秒→ 120s → 240s → 480s → 900s)
• 解决方案： 等待冷却期结束
• 预防： 在呼叫验证之前，确保电话号码正确

⚠️ 会话和数据问题

问题：容器重启后会话丢失

• 原因： Docker卷不持久
• 检查： docker volume ls | grep whatsapp-sessions
• 解决方案： 确保 whatsapp-sessions 卷存在并已装载

问题：邮件未出现在搜索中

• 原因： FTS5索引可能不同步或消息缺少正文
• 解决方案：

1. 检查消息是否存在：使用 list_messages 为了聊天 1. 验证搜索查询：尝试更简单的关键字 1. FTS5限制：仅媒体消息（无文本）不可搜索

问题：媒体下载失败

• 原因1： WhatsApp服务器上的媒体已过期（30天限制）
• 原因2： 消息ID无效或来自元数据跟踪之前
• 解决方案： 收到媒体后立即下载；旧媒体可能不可用

⚠️ 联系人和姓名解析

问题：模糊搜索匹配的联系人错误

• 原因： 多个联系人的名字相似
• 解决方案： 使用精确的JID而不是名称： send_message({ to: "1234567890@s.whatsapp.net", ... })
• 预防： 使用 search_contacts 首先找到确切的JID

问题：联系人姓名显示为电话号码

• 原因： WhatsApp的名称解析可能需要时间或失败
• 解决方案： 名称是异步解析的；等待消息到达
• 注： 这是化妆品；消息传递仍然适用于JID

⚠️ 备份与恢复

问题：需要备份/还原会话

• 备份（bash/zsh）：

  docker run --rm -v whatsapp-sessions:/data -v $(pwd):/backup alpine \
    tar czf /backup/whatsapp-backup.tar.gz /data

• 备份（PowerShell）：

  docker run --rm -v whatsapp-sessions:/data -v "${PWD}:/backup" alpine `
    tar czf /backup/whatsapp-backup.tar.gz /data

• 还原（bash/zsh）：

  docker run --rm -v whatsapp-sessions:/data -v $(pwd):/backup alpine \
    tar xzf /backup/whatsapp-backup.tar.gz -C /data --strip-components 1

• 还原（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. 搜索问题：
4. 报告错误： 包括日志、Docker版本和复制步骤

______________________________________________________________________

测试

测试通过以下方式在Docker中运行 tester-container --不需要本地构建工具。这 npm test 在主机上故意阻止脚本；请改用容器的默认CMD。

# Build the test image (tester-container is behind the 'test' Compose profile)
docker compose --profile test build tester-container

# Run all unit + integration tests (uses container default CMD)
docker compose --profile test run --rm tester-container

# Run a specific test file
docker compose --profile test run --rm tester-container npx tsx --test test/unit/crypto.test.ts

# One-time WhatsApp auth for e2e tests
docker compose --profile test run --rm tester-container npx tsx test/e2e/setup-auth.ts

# Run e2e tests with live session
docker compose --profile test run --rm tester-container npx tsx --test test/e2e/live.test.ts

看 文档/指南/开发者.md 查看完整的测试指南。

______________________________________________________________________

故障排除

🔍 诊断命令

运行诊断脚本以检查系统运行状况：

主机上需要Node.js。 如果你没有在本地安装Node.js，请使用下面的手动诊断程序——服务器本身在Docker中运行Node，正常使用不需要安装主机。

# Quick status check
node scripts/diagnostics.js

# Verbose output with full logs
node scripts/diagnostics.js --verbose

# JSON output for automation
node scripts/diagnostics.js --json

手动诊断：

# Check if container is running
docker compose ps

# View last 50 lines of logs
docker compose logs --tail 50 whatsapp-mcp-docker

# Check volumes exist (bash/zsh)
docker volume ls | grep whatsapp
# Check volumes exist (PowerShell)
docker volume ls | findstr whatsapp

# Verify encryption key is set (bash/zsh)
docker mcp secret ls | grep whatsapp-mcp-docker
# Verify encryption key is set (PowerShell)
docker mcp secret ls | findstr whatsapp-mcp-docker

# Check catalog registration
docker mcp catalog ls

# List all servers across all profiles
docker mcp profile server ls

# List servers for a specific profile (--profile flag does not exist; use --filter)
docker mcp profile server ls --filter profile=

# Test WhatsApp connection status (from MCP client)
get_connection_status

______________________________________________________________________

常见陷阱和解决方案

1.身份验证问题

问题： 配对代码返回400错误或过期

原因： WhatsApp速率限制配对尝试或代码在60秒内过期

解决方案：

• 如果速率受限，请在两次尝试之间等待10-15分钟
• 打电话前准备好WhatsApp移动应用程序 authenticate
• 如果配对代码失败，服务器会自动回退到二维码
• 二维码将在约20秒后过期——如果过期，请申请新的二维码

预防： 打开WhatsApp→ 设置→ 已关联设备→ “链接设备” 之前 召唤 authenticate，因此您可以立即输入代码。通过 waitForLink: true 如果您希望工具轮询直到链接（注意：这可能会超过某些MCP客户端上的工具调用超时时间——请参阅 auth_wait_for_link config）。

______________________________________________________________________

问题： “已通过身份验证”，但消息未发送

原因： 会话可能已过时或WhatsApp已断开连接

解决方案：

# Check connection status
get_connection_status

# If disconnected, check logout reason
# If reason is "revoked", "banned", or "unlinked" → re-authenticate
authenticate({ phoneNumber: "+1234567890" })

______________________________________________________________________

2.会话到期

问题： 在一段时间不活动后“WhatsApp未连接”

原因： WhatsApp链接的设备会话在大约20天不活动后过期

解决方案：

1. 呼叫 authenticate 再次使用相同的电话号码
2. 会话将恢复（如果仍然在20天内，则无需重新链接）
3. 如果过期，您需要使用配对码或二维码重新链接

预防： 每两周至少发送一条消息或使用服务器一次。

______________________________________________________________________

3.利率限制

问题： “超过速率限制（60条消息/分钟）”

原因： WhatsApp可能会禁止发送过多消息过快的帐户

解决方案：

• 等待60秒以重置速率限制
• 降低消息频率
• 增加 RATE_LIMIT_PER_MIN 只有当你有合法的高容量使用时

警告： 激进的消息传递可能会导致您的WhatsApp帐户被禁止。

______________________________________________________________________

问题： “身份验证尝试次数过多（每30分钟5次）”

原因： 身份验证限制为每30分钟5次尝试

解决方案：

• 等待冷却期（指数回退：60秒→ 120s → 240s → 480s → 900s)
• 尝试失败后不要立即重试
• 如果配对代码失败，请等待二维码回退，而不是重试

______________________________________________________________________

4.联系解决问题

问题： “无法解析收件人”或匹配了错误的联系人

原因： 模糊匹配找到多个候选人或没有匹配项

解决方案：

# Get exact JID from list_chats
list_chats()

# Use JID directly (bypasses fuzzy matching)
send_message({ to: "1234567890@c.us", message: "Hello" })

提示： 联系人姓名可能不会在收到第一条消息后立即解析——请等待几秒钟进行姓名解析。

______________________________________________________________________

5.媒体下载失败

问题： “没有为此邮件存储媒体元数据”

原因： 在启用元数据跟踪之前收到媒体，或媒体已过期

解决方案：

• WhatsApp服务器上的媒体将在30天后过期
• 只有启用服务器后收到的媒体才能下载
• 检查 has_media 旗在 list_messages 查看媒体是否可用

______________________________________________________________________

问题： “超出媒体存储配额”

原因： 总媒体目录已达到512 MB的限制

解决方案：

# Check media directory size
docker compose exec whatsapp-mcp-docker du -sh /data/sessions/media

# Delete old media files manually or wait for auto-purge
# Auto-purge runs hourly if MESSAGE_RETENTION_DAYS > 0

______________________________________________________________________

6.搜索不返回任何结果

问题： search_messages 找不到任何东西

原因：

• FTS5索引可能没有赶上（延迟索引）
• 邮件已加密，但搜索索引有明文
• 查询语法错误（布尔运算符需要大写）

解决方案：

# Try simpler query without operators
search_messages({ query: "hello" })  # Instead of "hello AND world"

# Use quotes for exact phrases
search_messages({ query: "\"exact phrase\"" })

# Check if messages exist
list_messages({ chat: "Contact Name", limit: 10 })

______________________________________________________________________

7.集装箱问题

问题： 容器无法启动

解决方案：

# Check logs
docker compose logs whatsapp-mcp-docker

# Verify volumes exist
docker volume ls | grep whatsapp

# Rebuild image
docker compose build --no-cache

# Remove and recreate
docker compose down -v
docker compose up -d

______________________________________________________________________

问题： 内存使用率高

原因： 消息历史同步将许多消息加载到内存中

解决方案：

• 集 MESSAGE_RETENTION_DAYS 限制存储的消息
• 在中使用分页 list_messages （限制：50，页码：0，1，2…）
• 定期重启容器以清空内存

______________________________________________________________________

身份验证失败

如果配对码返回400错误，服务器将自动退回二维码身份验证——二维码将作为图像和数据URI直接在工具响应中返回（将URI粘贴到任何浏览器中查看）。查看容器日志以了解详细信息： docker compose logs whatsapp-mcp-docker.

价格有限（429）

WhatsApp的速率限制了配对尝试。请等待10-15分钟，然后重试。

会话已过期

WhatsApp会话在大约20天不活动后过期。服务器会自动检测到这一点：它发送 notifications/disconnected MCP通知您的客户端，清理过时的会话文件，并在中报告原因 get_connection_status.致电 authenticate 再次重新链接。

对于短暂的断开连接（网络短暂中断），服务器会在5秒后自动尝试重新连接。60秒的健康心跳检测到无声连接中断。在放弃之前，启动会以指数回退重试5次。

容器无法启动

docker compose up -d
docker compose logs -f whatsapp-mcp-docker

______________________________________________________________________

许可证

Apache许可证2.0——请参阅 许可证 了解详情。

______________________________________________________________________

免责声明

此项目与WhatsApp或Meta无关。WhatsApp不正式支持非官方的API客户端。使用风险由您自行承担，并遵守WhatsApp的服务条款。

______________________________________________________________________

联系

• AI作者： Qwen3编码器下一个•MiniMax-M2.7•Qwen3.5•Nemotron-3-Super
• 主任： 本杰明·阿洛尔-- Benjamin.Alloul@gmail.com
• 问题：
• 讨论：