使用说明

WhatsApp MCP服务器

一 MCP（模型上下文协议）将Claude和其他LLM客户端连接到WhatsApp的服务器。建在百利甜酒该库原生实现了WhatsApp Web协议，无需浏览器自动化。

特性

whatsapp_get_status --检查连接状态（已连接、等待QR、错误）
whatsapp_list_chats --列出可用的聊天记录和群组及其元数据
whatsapp_list_messages --列出服务器本地存储中的最新消息（运行时观察到；可选持久性）
whatsapp_send_message --向联系人或组发送短信
whatsapp_send_file --发送文件/媒体（文档/图像/视频/音频/语音备忘）
whatsapp_get_media --直接以Base64格式获取媒体，无需本地下载（新增！）
whatsapp_download_media --将附件（包括语音备忘）下载到本地文件
whatsapp_get_group_info --获取组详细信息、参与者和管理员信息

先决条件

Node.js >= 18
WhatsApp帐户 链接到手机
MCP兼容客户端 （克劳德桌面、克劳德代码等）

兼容性： 两者都适用 常规WhatsApp 和 WhatsApp商业版 账户。Baileys实现了WhatsApp Web多设备协议，这两种帐户类型都是相同的。此服务器不支持特定于业务的功能（目录、自动回复、标签）。

重要提示： 此服务器需要 @whiskeysockets/baileys@^7.0.0-rc.9 或稍后。旧版本可能无法为新设备链接生成有效的二维码。

快速开始

1.克隆和构建

git clone https://github.com/ydmw74/whatsapp-mcp-server.git
cd whatsapp-mcp-server
npm install
npm run build

2.首次运行——二维码验证

手动运行服务器一次以完成二维码配对：

node dist/index.js

您的终端上将显示一个二维码。用手机扫描：

WhatsApp>设置>链接设备>链接设备

成功配对后，会话将持久化 ~/.whatsapp-mcp/auth。除非解除设备链接，否则您不需要再次扫描。

注：使用 whatsapp_list_messages，在消息到达时保持服务器运行。服务器只能列出它观察到的消息（并且可以选择持久化）。

3.配置您的MCP客户端

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp-server/dist/index.js"]
    }
  }
}

克劳德代码

claude mcp add whatsapp node /absolute/path/to/whatsapp-mcp-server/dist/index.js

4.可选：共享HTTP模式（单服务器进程）

如果你想为多个客户端运行一个长时间运行的MCP服务器进程，请在HTTP模式下运行：

WHATSAPP_MCP_TRANSPORT=http WHATSAPP_HTTP_HOST=127.0.0.1 WHATSAPP_HTTP_PORT=8787 WHATSAPP_HTTP_PATH=/mcp node dist/index.js

或者使用npm脚本：

WHATSAPP_HTTP_HOST=127.0.0.1 WHATSAPP_HTTP_PORT=8787 WHATSAPP_HTTP_PATH=/mcp npm run start:http

然后将MCP客户端配置为使用URL端点（Streamable HTTP），例如使用Codex：

codex mcp add whatsapp --url http://127.0.0.1:8787/mcp

配置

环境变量	默认值	描述
`WHATSAPP_AUTH_DIR`	`~/.whatsapp-mcp/auth`	会话持久性目录
`WHATSAPP_DEVICE_NAME`	（未设置）	WhatsApp中显示的可选链接设备标签（“链接设备”），例如。 `WHATSAPP_DEVICE_NAME=MyAgent-1` （将显示为 `MyAgent-1 (Mac OS)` 或 `... (Ubuntu)`).
`WHATSAPP_RELINK`	（未设置）	在非交互式环境中强制重新链接。使用 `backup` （或 `1`/`true`)将现有的auth-dir移到一边，或 `delete` 将其删除
`WHATSAPP_EXIT_AFTER_PAIR`	`auto`	如果本次运行中显示了二维码，配对成功后会自动退出。默认情况下，仅对交互式终端运行（TTY）启用。
`WHATSAPP_PERSIST_MESSAGES`	`false`	将本地消息存储持久化到磁盘(`message-store.json`).
`WHATSAPP_MAX_MESSAGES_PER_CHAT`	`200`	本地消息存储的每次聊天保留限制。
`WHATSAPP_MAX_MESSAGES_TOTAL`	`2000`	本地邮件存储的全局保留限制。
`WHATSAPP_MCP_TRANSPORT`	`stdio`	MCP传输模式： `stdio` 或 `http` (`http` =流式HTTP服务器）。
`WHATSAPP_HTTP_HOST`	`127.0.0.1`	HTTP模式的绑定地址。使用 `0.0.0.0` 如果客户端从其他主机连接。
`WHATSAPP_HTTP_PORT`	`8787`	HTTP模式的TCP端口。
`WHATSAPP_HTTP_PATH`	`/mcp`	MCP请求的HTTP端点路径。
`WHATSAPP_UPLOAD_DIR`	`/tmp/whatsapp-uploads`	上传文件的目录（HTTP模式）。
`WHATSAPP_UPLOAD_MAX_SIZE`	`52428800`	最大上传文件大小（以字节为单位）（默认值：50 MB）。

工具参考

`whatsapp_get_status`

检查WhatsApp是否已连接并准备就绪。

参数： 无

退货： 连接状态、电话号码或二维码（如果身份验证待定）。

`whatsapp_list_chats`

列出可用的WhatsApp聊天记录。

参数：

limit （数字，1-100，默认值：20）--可返回的最大聊天记录数

退货： 聊天记录列表，包括ID、姓名、类型（组/DM）和未读计数。

`whatsapp_list_messages`

列出服务器本地消息存储中的最新消息。

参数：

chat_id （string，可选）--聊天JID（DM或group）。如果省略，则返回所有聊天记录中的最新消息。
limit （number，1-100，默认值：20）--要返回的最大消息数

退货： 带有时间戳、发件人和文本的格式化消息列表。

笔记：

只有正在运行的服务器观察到的消息可用。
要在重新启动时保留消息，请设置 WHATSAPP_PERSIST_MESSAGES=1 （商店 message-store.json 在auth-dir旁边）。
如果消息包括媒体，则列表包括基本媒体元数据（种类、mimetype等）。使用 whatsapp_download_media 下载附件。

`whatsapp_send_message`

发送短信。

参数：

chat_id （string）-带有国家代码的电话号码（例如。， 4915123456789)或完整的JID
text （string）--消息文本（最多4096个字符）

退货： 消息ID和时间戳。

`whatsapp_send_file`

发送文件/媒体消息（文档/图像/视频/音频/语音备忘）。

参数：

chat_id （string）--带国家代码或完整JID的电话号码
path （string）--本地文件路径（支持 ~/ 扩展）
kind （字符串，可选）-- document|image|video|audio|voice （默认值： document)
caption （字符串，可选）--标题（图像/视频/文档）
mimetype （string，可选）--MIME类型覆盖
fileName （字符串，可选）--文件名覆盖（仅限文档）

退货： 消息ID和时间戳。

`whatsapp_download_media`

从服务器观察到的邮件中下载附件（包括语音备忘）。

参数：

chat_id （string）--聊天JID（来自 whatsapp_list_messages)
message_id （string）--消息ID（来自 whatsapp_list_messages)
output_dir （string，可选）--文件写入目录（支持 ~/ 扩展）

退货： 绝对文件 path 和 media 元数据。

`whatsapp_get_media`

直接从服务器以Base64格式获取媒体（附件），无需保存到磁盘。

参数：

chat_id （string）--聊天JID（来自 whatsapp_list_messages)
message_id （string）--消息ID（来自 whatsapp_list_messages)
format （string，可选）--返回格式： "base64" 对于原始base64（默认）或 "data_url" 用于图像数据URL

退货： Base64编码媒体和 media 元数据。

笔记：

仅适用于服务器启动后观察到的消息
无需下载本地文件
支持图像、视频、文档、音频和语音备忘

`whatsapp_get_group_info`

获取详细的组信息。

参数：

group_id （string）-组JID（例如。， 120363012345678901@g.us)

退货： 组主题、描述、具有管理员状态的参与者列表。

HTTP文件传输端点（HTTP模式）

在HTTP模式下运行时，服务器为远程文件传输提供了两个额外的端点。这些对于无法直接访问服务器文件系统的远程MCP客户端至关重要。

`POST /upload` --将文件上传到服务器

curl -s -F "file=@/local/path/photo.jpg" http://server:8787/upload

答复：

{"path": "/tmp/whatsapp-uploads/a1b2c3d4-photo.jpg", "size": 123456, "name": "photo.jpg"}

使用返回的 path 和 whatsapp_send_file。文件会在1小时后自动清理。

`GET /download?path=...` --从服务器下载文件

curl -s -o local-file.jpg "http://server:8787/download?path=/root/whatsapp-mcp-data/downloads/whatsapp-ABC123.jpeg"

仅提供来自允许目录的文件(/tmp，上传目录，下载目录）以防止任意文件访问。

典型工作流程：

whatsapp_download_media → 返回服务器本地路径
GET /download?path=<server-path> → 将文件下载到本地计算机

运作原理

默认情况下(WHATSAPP_MCP_TRANSPORT=stdio)，您的MCP客户端（Claude Desktop、Claude Code等）在后台自动启动和管理服务器进程。

当你在Claude Desktop中打开聊天时，它会自动生成 node dist/index.js 作为孩子，处理并与之交流标准（标准输入/标准输出）。当您关闭聊天时，进程将停止。你不需要自己管理。

这 仅手动步骤 是一次性二维码身份验证（请参阅快速入门，步骤2）。之后，会话被持久化到磁盘，服务器在每次后续启动时都会自动重新连接。

在HTTP模式下(WHATSAPP_MCP_TRANSPORT=http)，您运行一个持久服务器进程，客户端通过URL连接到它（例如 http://server:8787/mcp).

建筑

stdio 模式（本地子进程）：

┌──────────────────┐     stdio      ┌──────────────────┐
│  Claude / LLM    │ ◄──────────── │  MCP Server      │
│  Client          │ ──────────── │  (this project)  │
└──────────────────┘               └────────┬─────────┘
                                            │
                                   Baileys Protocol
                                            │
                                   ┌────────▼─────────┐
                                   │  WhatsApp Web    │
                                   │  Servers         │
                                   └──────────────────┘

http 模式（共享守护进程）：

┌──────────────────┐      HTTP      ┌──────────────────┐
│  MCP Client A    │ ────────────► │                  │
├──────────────────┤                │  MCP Server      │
│  MCP Client B    │ ────────────► │  (single process)│
└──────────────────┘                └────────┬─────────┘
                                             │
                                    Baileys Protocol
                                             │
                                    ┌────────▼─────────┐
                                    │  WhatsApp Web    │
                                    │  Servers         │
                                    └──────────────────┘

会话状态会持久化到磁盘，因此只需要重新验证一次。

PM2部署（Linux，网络共享）

如果您希望在局域网中的专用Linux主机上运行单个MCP服务器，建议使用此设置。

重要提示： Baileys 7.x（此项目需要 ^7.0.0-rc.9)QR码验证正常工作需要。如果您遇到二维码问题，请确保安装了正确的Baileys版本。

0.新鲜服务器预运行（如果Node.js/npm缺失）

在新的Debian主机上，首先安装所需的基本软件包：

apt-get update -y
apt-get install -y nodejs npm git rsync

1.安装PM2

npm install -g pm2

2.构建服务器

cd /home/<linux-user>/whatsapp-mcp-server
npm install
npm run build

3.使用PM2（HTTP模式）启动MCP服务器

绑定到所有接口(0.0.0.0)如果客户端从其他机器连接：

WHATSAPP_MCP_TRANSPORT=http \
WHATSAPP_HTTP_HOST=0.0.0.0 \
WHATSAPP_HTTP_PORT=8787 \
WHATSAPP_HTTP_PATH=/mcp \
WHATSAPP_AUTH_DIR=/home/<linux-user>/whatsapp-mcp-data/auth \
pm2 start node --name whatsapp-mcp -- dist/index.js

您还可以使用：

WHATSAPP_HTTP_HOST=0.0.0.0 WHATSAPP_HTTP_PORT=8787 WHATSAPP_HTTP_PATH=/mcp pm2 start npm --name whatsapp-mcp -- run start:http

建议（独立于路径）：使用附带的PM2配置文件：

cd /home/<linux-user>/whatsapp-mcp-server
pm2 start ecosystem.config.cjs

提供的 ecosystem.config.cjs 使用：

cwd: __dirname （无论克隆目录如何，都能正常工作）
WHATSAPP_AUTH_DIR 从当前Linux用户的主目录动态获取，例如。 /home/<linux-user>/whatsapp-mcp-data/auth

4.在重启过程中保持PM2不变

pm2 startup
pm2 save

5.有用的PM2命令

pm2 status
pm2 logs whatsapp-mcp
pm2 restart whatsapp-mcp
pm2 stop whatsapp-mcp

检查MCP HTTP侦听器：

ss -lntp | grep 8787

5.1 PM2日志中的二维码（扫描友好输出）

PM2在每行前添加时间戳/流程元数据，这可能会使终端QR难以扫描。使用辅助脚本（来自存储库根目录）打印最新的完整二维码块：

./scripts/show-whatsapp-qr.sh

可选：传递其他PM2应用程序名称：

./scripts/show-whatsapp-qr.sh whatsapp-mcp

6.将MCP客户端连接到Linux主机

法典

codex mcp add whatsapp --url http://<linux-server-ip>:8787/mcp

克劳德桌面(`claude_desktop_config.json`)

使用 mcp-remote 将Claude Desktop连接到您的远程HTTP服务器。

重要提示： mcp-remote 默认情况下只允许HTTPS URL。由于服务器运行在纯HTTP（无TLS）上，您必须添加 --allow-http flag——否则连接将失败，原因如下：
Error: Non-HTTPS URLs are only allowed for localhost or when --allow-http flag is provided

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://<linux-server-ip>:8787/mcp",
        "--allow-http"
      ]
    }
  }
}

编辑后 claude_desktop_config.json，重新启动Claude Desktop应用程序以应用更改。

提示： 如果您的服务器可以通过HTTPS访问（例如，在具有TLS的反向代理后面），请省略 --allow-http 旗帜。

克劳德代码（CLI）

claude mcp add --transport http whatsapp http://<linux-server-ip>:8787/mcp

注： Claude Code的内置HTTP传输直接接受纯HTTP URL——否 --allow-http 需要旗帜。

7.链接故障排除

如果WhatsApp目前拒绝新的链接设备，这通常是WhatsApp的临时问题。
保持PM2进程运行，稍后重试QR链接。
要强制进行新的二维码尝试：

pm2 restart whatsapp-mcp

WhatsApp宣布会话无效(device_removed，代码401）

如果您在错误日志中看到以下内容：

"stream errored out" ... "code":"401" ... "type":"device_removed"

WhatsApp已远程撤销会话（例如，因为您将设备与手机断开链接，或者WhatsApp强制重新链接）。服务器无法与现有的身份验证文件重新连接——您必须删除它们并重新配对：

pm2 stop whatsapp-mcp
rm -rf ~/whatsapp-mcp-data/auth/*   # adjust path to your WHATSAPP_AUTH_DIR
pm2 start ecosystem.config.cjs
./scripts/show-whatsapp-qr.sh       # or: whatsapp-qr

然后扫描二维码 WhatsApp>设置>链接设备>链接设备.

8.快速恢复（复制/粘贴runbook）

当远程部署未按预期运行时，按顺序使用这些命令：

# 1) Process state
pm2 status whatsapp-mcp

# 2) Recent logs
pm2 logs whatsapp-mcp --lines 100 --nostream

# 3) Ensure HTTP endpoint is listening
ss -lntp | grep 8787

# 4) Restart app and refresh environment
pm2 restart whatsapp-mcp --update-env

# 5) Re-check logs after restart
pm2 logs whatsapp-mcp --lines 100 --nostream

如果PM2日志中无法扫描QR输出：

./scripts/show-whatsapp-qr.sh

完全重新链接（会话无效或损坏）：

pm2 stop whatsapp-mcp
rm -rf ~/whatsapp-mcp-data/auth/*   # adjust to your WHATSAPP_AUTH_DIR
pm2 start ecosystem.config.cjs
./scripts/show-whatsapp-qr.sh       # or: whatsapp-qr

如果PM2正在运行，但在重新启动后未恢复：

pm2 startup systemd -u root --hp /root
pm2 save
systemctl status pm2-root

提示：如果此服务器在您的网络中运行，请使用防火墙规则和/或具有身份验证/TLS的反向代理来保护访问。不要将未经身份验证的MCP端点直接暴露给公共互联网。

安全注意事项

会话数据 存储在本地 ~/.whatsapp-mcp/auth.保护此目录-任何有权访问的人都可以冒充您的WhatsApp帐户。
消息可以存储在本地 在记忆中 whatsapp_list_messages （并可选地持续到 message-store.json).将存储的消息数据视为敏感数据。
LLM客户端应该 始终与用户确认 在通过以下方式发送消息之前 whatsapp_send_message.
该项目使用非官方的WhatsApp Web协议。WhatsApp可能会屏蔽违反其服务条款的帐户。负责任地使用。

局限性

消息历史记录有限：服务器列出了它在运行时观察到的最新消息（并且可以选择持久化）。它不会从WhatsApp获取任意聊天历史记录。
媒体下载仅限于观察到的消息: whatsapp_download_media 只能下载服务器自启动以来观察到的消息的媒体（它将原始消息保存在内存中，以供最近有界的窗口使用）。
单次会话：一次只能链接一个WhatsApp帐户。

发展

# Install dependencies
npm install

# Run in development mode (auto-reload)
npm run dev

# Build
npm run build

# Clean build artifacts
npm run clean

致谢

百利甜酒 -WhatsApp Web API库
开爪 --WhatsApp集成架构的灵感
MCP TypeScript SDK --模型上下文协议SDK

许可证

麻省理工学院

使用说明

WhatsApp MCP服务器

特性

先决条件

快速开始

1.克隆和构建

2.首次运行——二维码验证

3.配置您的MCP客户端

克劳德桌面

克劳德代码

4.可选：共享HTTP模式（单服务器进程）

配置

工具参考

whatsapp_get_status

whatsapp_list_chats

whatsapp_list_messages

whatsapp_send_message

whatsapp_send_file

whatsapp_download_media

whatsapp_get_media

whatsapp_get_group_info

HTTP文件传输端点（HTTP模式）

POST /upload --将文件上传到服务器

GET /download?path=... --从服务器下载文件

运作原理

建筑

PM2部署（Linux，网络共享）

0.新鲜服务器预运行（如果Node.js/npm缺失）

1.安装PM2

2.构建服务器

3.使用PM2（HTTP模式）启动MCP服务器

4.在重启过程中保持PM2不变

5.有用的PM2命令

5.1 PM2日志中的二维码（扫描友好输出）

6.将MCP客户端连接到Linux主机

法典

克劳德桌面(claude_desktop_config.json)

克劳德代码（CLI）

7.链接故障排除

8.快速恢复（复制/粘贴runbook）

安全注意事项

局限性

发展

致谢

许可证

相关 MCP

知识图谱记忆服务器

学术论文搜索工具

LINE桌面消息控制工具

聊天机器人服务器

Discord API管理服务

论文检索聊天机器人

`whatsapp_get_status`

`whatsapp_list_chats`

`whatsapp_list_messages`

`whatsapp_send_message`

`whatsapp_send_file`

`whatsapp_download_media`

`whatsapp_get_media`

`whatsapp_get_group_info`

`POST /upload` --将文件上传到服务器

`GET /download?path=...` --从服务器下载文件

克劳德桌面(`claude_desktop_config.json`)