WhatsApp Web MCP Server

非常重要

不使用 Meta（Business-）API 自动化处理 Whatsapp 消息，违反 WhatsApp 的服务条款！ 你必须为使用此 MCP 服务的一切行为承担全部责任。你的账号可能会被标记或限制。

MCP WhatsApp Web（TypeScript）

一个以 TypeScript 实现的 WhatsApp Web 模型上下文协议（MCP）服务。本项目是对原始 whatsapp-mcp 仓库的 TypeScript 移植。

使用此 MCP 服务，你可以：

• 搜索和阅读个人 WhatsApp 消息（包括媒体）
• 搜索联系人
• 向个人或群组发送消息
• 发送和接收媒体文件（图片、视频、文档、音频）

功能

• TypeScript 实现：代码库完整类型化，提升开发体验和代码可靠性
• 可选的 WhatsApp 后端：默认使用 whatsapp-web.js，也可选用无需浏览器即可运行的 Baileys 后端
• MCP 服务：实现 模型上下文协议，可与 AI 助手无缝集成
• 媒体支持：发送和接收图片、视频、文档及音频消息
• 多种传输选项：支持 stdio 和 Streamable HTTP 传输，也可由单个进程同时使用两者（通过 stdio 启动并设置 MCP_HTTP_PORT，即可额外开放 http://127.0.0.1:<port>/mcp；也可使用 --http 仅运行 HTTP）
• 灵活的身份验证：支持二维码（作为 MCP 图片工具）、配对码（通过 request_pairing_code 工具获取，或在启动时通过 WHATSAPP_PAIRING_PHONE_NUMBER 自动打印到 stderr），以及供 HTTP 客户端使用的可选 OAuth 流程（MCP_OAUTH=true）。浏览器授权页面会显示 WhatsApp 二维码；解除 WhatsApp 关联后会撤销令牌，客户端将自动重新进行身份验证

架构

此 MCP 服务由以下部分组成：

1. TypeScript MCP 服务：实现模型上下文协议，为 AI 助手提供标准化工具，以便与 WhatsApp 交互
2. WhatsApp 后端：通过共享服务接口选择 web.js/Puppeteer 或 Baileys/WebSocket，处理身份验证，并管理消息的发送和接收
3. 工具实现：提供联系人、聊天、消息、媒体和身份验证等各类工具

前置条件

• Node.js >= 22.0.0（Baileys SQLite 依赖推荐使用 Node 22 或 24）
• npm 或 yarn
• 对于默认的 webjs 后端：Google Chrome 或 Microsoft Edge（会自动检测；视频/GIF 编解码支持需要使用它；其他操作可使用 Puppeteer 自带的 Chromium）
• 对于 baileys：安装可选依赖，包括原生 better-sqlite3 模块。运行时不需要 Chrome、Edge 或 Chromium。

FFmpeg 会通过 npm 包 ffmpeg-static 自动附带，无需手动安装。你可以将 FFMPEG_PATH 环境变量指向自己的二进制文件以覆盖默认设置。

安装

npx

npx mcp-whatsapp-web

手动安装

1. 克隆此仓库

   git clone https://github.com/mario-andreschak/mcp-whatsapp-web.git
   cd mcp-whatsapp-web
   

2. 安装依赖

   npm install
   

3. 构建项目

   npm run build
   

4. 配置环境变量（可选）

   复制示例环境文件，并根据需要进行修改：

   cp .env.example .env
   

   你可以通过 WHATSAPP_BACKEND 选择后端、调整日志级别、固定 WhatsApp Web 版本，或覆盖自动检测到的浏览器（BROWSER_EXECUTABLE_PATH）和 ffmpeg 二进制文件（FFMPEG_PATH）。WHATSAPP_HEADLESS=false 会显示 web.js 浏览器窗口，WHATSAPP_SESSION_DIR 可更改其持久化配置文件的存放位置。请使用绝对会话目录，以便在不同工作目录间保持一致。

选择后端

WHATSAPP_BACKEND=webjs 是默认设置，可保留现有会话和 MCP 工具名称。它使用专用的持久化 LocalAuth 配置文件，而非你的个人 Chrome 配置文件。现在，它会保留浏览器原生的用户代理和图形默认设置，不使用 Puppeteer 的自动化横幅标记，并保持浏览器沙箱启用。需要禁用沙箱的容器可以显式设置 WHATSAPP_NO_SANDBOX=true。这些设置不能保证自动化操作无法被检测到。

要使用可选的 Baileys 后端，请在 MCP 客户端配置或 .env 中设置以下变量，然后重启服务：

WHATSAPP_BACKEND=baileys
BAILEYS_SESSION_DIR=C:/path/to/your/baileys-sessions

BAILEYS_SESSION_DIR 默认为 <working directory>/baileys-sessions；请将上面的示例替换为你自己的绝对路径。使用此后端时，需另行通过 get_qr_code 或 request_pairing_code 配对。现有的 WHATSAPP_PAIRING_PHONE_NUMBER 选项也可使用。Baileys 无法复用 web.js 浏览器配置文件。你可以切换回 webjs 并继续使用其现有会话。

Baileys 和 SQLite 是固定版本的可选依赖，通过常规的 npm install 安装。如果包管理器未安装它们，请运行 npm install --include=optional。SQLite 使用原生附加组件；需要受支持的预编译二进制文件或本地原生构建工具链。若要在为 Baileys 安装或使用现有系统浏览器时避免下载 Chromium，请使用：

$env:PUPPETEER_SKIP_DOWNLOAD = 'true'
npm install --include=optional
npm run build

在 macOS/Linux 上，对应的安装命令为 PUPPETEER_SKIP_DOWNLOAD=true npm install --include=optional。选择 Baileys 时只会加载其驱动程序，不会启动或清理浏览器进程。如果后端不可用，系统会报错；不会静默切换驱动程序，也不会通过其他后端重试发送。

Baileys 会话和历史记录

• 凭据、Signal 密钥、联系人、聊天和消息会持久化在 BAILEYS_SESSION_DIR/session.sqlite 中。请妥善保护整个目录，并勿将其纳入版本控制。一个会话目录只能由一个正在运行的服务使用。不同账号请使用单独的目录。
• 正常关闭会保留会话。显式退出登录或身份验证失效时，会清除 Baileys 凭据和缓存的账号数据，并撤销其 OAuth 访问令牌。Baileys 的 HTTP OAuth 状态与 web.js 分开，存储在 BAILEYS_SESSION_DIR/oauth-store.json 中。
• get_backend_status 会报告当前使用的后端、身份验证状态、存储的记录数和历史记录同步状态。已连接并不代表历史记录已接收完毕。历史状态为 available 表示本地数据可用，并不代表 WhatsApp 已提供完整存档。
• 联系人和历史记录工具会查询本地同步存储。系统会请求初次完整历史记录同步；对于大型账号，此过程可能需要一些时间。如果已知聊天中的消息少于请求数量，list_messages 可能会请求最多 100 条更早的消息，并设有等待时限和每个聊天的冷却时间。较晚到达的历史记录批次会保存下来，供后续查询使用。WhatsApp 仍可能只提供账号部分历史记录。
• 请将返回的消息 ID 视为不透明值，并使用当前后端的 ID。支持旧版 @c.us 电话号码输入、@s.whatsapp.net、群组和 @lid 标识符；已知的 LID/电话号码映射会持久化保存。web.js 的消息 ID 不能传给 Baileys 使用，反之亦然。
• 文本、媒体、下载、语音消息和现有身份验证工具使用相同的 MCP 接口。语音消息输入必须是本地文件或 base64；发送前会由 FFmpeg 将其转换为单声道 Opus/Ogg。如果转换失败，工具会报告错误，不会改为发送其他消息类型。

Baileys 后端需显式启用，且版本固定为 7.0.0-rc14。升级前请查看上游变更，尤其是身份验证和消息格式迁移。请参阅 Baileys 文档和发布历史。

使用 FLUJO 安装

FLUJO 提供了简化的安装流程：

1. 在 FLUJO 中导航到 MCP 部分
2. 点击“Add Server”
3. 复制并粘贴此 GitHub 仓库 URL：https://github.com/mario-andreschak/mcp-whatsapp-web
4. 点击“Parse”、“Clone”、“Install”、“Build”和“Update Server”

FLUJO 将自动为你处理克隆、依赖项安装和构建流程。

使用方法

启动 MCP 服务

npm start

默认情况下，这会使用 stdio 传输启动 MCP 服务，适用于与 Claude Desktop 或类似应用集成。

重要： 首次启动服务后，你必须使用 get_qr_code 工具进行身份验证，并用手机扫描二维码。详细说明请参阅身份验证部分。

开发模式

npm run dev

这会以开发模式启动服务，并启用 TypeScript 监视模式和自动重启服务。

使用 MCP Inspector 调试

npm run debug

这会启动 MCP Inspector 工具，它提供了一个 Web 界面，用于测试和调试你的 MCP 服务。Inspector 允许你：

• 查看所有可用工具及其架构
• 直接执行工具并查看其响应
• 无需连接 AI 助手即可测试服务
• 调试工具执行并检查响应

连接到 Claude Desktop

1. 为 Claude Desktop 创建配置文件：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "npx",
         "args": [
           "mcp-whatsapp-web"
         ]
       }
     }
   }
   

   将 PATH_TO 替换为仓库的绝对路径。

2. 将其保存为 claude_desktop_config.json，并放入 Claude Desktop 配置目录：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

3. 重启 Claude Desktop

连接到 Cursor

1. 为 Cursor 创建配置文件：

   {
     "mcpServers": {
       "whatsapp": {
         "command": "node",
         "args": [
           "PATH_TO/dist/index.js"
         ]
       }
     }
   }
   

   将 PATH_TO 替换为仓库的绝对路径。

2. 将其保存为 mcp.json，并放入 Cursor 配置目录：

   • macOS/Linux：~/.cursor/mcp.json
   • Windows：%USERPROFILE%\.cursor\mcp.json

3. 重启 Cursor

身份验证

首次运行服务时，你需要通过 WhatsApp 进行身份验证：

1. 启动 MCP 服务
2. 重要： 必须使用 get_qr_code 工具生成二维码
   • 在 Claude 或其他 AI 助手中，明确要求“使用 get_qr_code 工具验证 WhatsApp”
   • 助手会调用此工具并显示二维码图片
3. 使用 WhatsApp 手机应用扫描二维码
   • 在手机上打开 WhatsApp
   • 前往 Settings > Linked Devices > Link a Device
   • 将手机摄像头对准显示的二维码

你的会话将保存在本地的 whatsapp-sessions 目录中，并在后续运行时自动复用。如果不使用二维码进行身份验证，你将无法使用任何 WhatsApp 功能。

身份验证状态和退出登录

你可以查看当前身份验证状态并管理会话：

• 使用 check_auth_status 工具确认当前是否已通过身份验证
• 如果需要使用其他 WhatsApp 账号进行身份验证，或重新验证：
  1. 使用 logout 工具退出当前会话
  2. 然后使用 get_qr_code 工具通过新的二维码进行身份验证

以下情况尤其适合使用此功能：

• 你想在不同的 WhatsApp 账号之间切换
• 会话已过期或失效
• 遇到连接问题，需要重新进行身份验证

可用的 MCP 工具

身份验证

• get_qr_code- 获取用于 WhatsApp Web 身份验证的二维码
• check_auth_status- 检查当前是否已通过 WhatsApp 身份验证
• logout- 退出 WhatsApp 并清除当前会话

联系人

• search_contacts- 按姓名或电话号码搜索联系人
• get_contact- 获取特定联系人的信息

聊天

• list_chats- 列出可用聊天及其元数据
• get_chat- 获取特定聊天的信息
• get_direct_chat_by_contact- 查找与特定联系人的直接聊天

消息

• list_messages- 根据可选筛选条件检索消息
• get_message- 按 ID 获取特定消息
• send_message- 向聊天发送文本消息

媒体

• send_file- 向聊天发送文件（图像、视频、文档）
• send_audio_message- 发送音频消息（语音留言）
• download_media- 从消息中下载媒体

浏览器进程管理

此 MCP 服务使用 Puppeteer 控制 Chrome 浏览器，以连接 WhatsApp Web。该服务包含一套完善的浏览器进程管理系统，可防止出现孤立的 Chrome 进程。

自动清理浏览器

该服务会自动：

• 使用 PID 跟踪系统跟踪 Chrome 浏览器进程
• 在启动时清理孤立进程
• 在关闭期间正确关闭浏览器进程
• 在 .chrome-pids.json 中保存浏览器 PID 记录

手动清理浏览器

如果发现未被自动清理的孤立 Chrome 进程，可以使用附带的清理工具：

npm run cleanup-browsers

此工具将：

1. 扫描可能与 WhatsApp Web 相关的 Chrome 进程
2. 显示可能孤立的进程列表
3. 在终止进程前请求确认
4. 清理 PID 跟踪文件

开发

项目结构

• src/index.ts- 入口点
• src/server.ts- MCP 服务实现
• src/services/whatsapp.ts- WhatsApp Web 服务
• src/tools/- 各种 WhatsApp 功能的工具实现
• src/types/- TypeScript 类型定义
• src/utils/- 实用函数

脚本

• npm run build- 构建 TypeScript 代码
• npm run dev- 在监视模式下运行开发环境
• npm run lint- 运行 ESLint
• npm run format- 使用 Prettier 格式化代码
• npm run cleanup-browsers- 检测并清理孤立的 Chrome 浏览器进程
• npm test - 运行单元测试套件（速度快，无需浏览器）
• npm run test:watch - 在开发期间以监视模式运行单元测试
• npm run test:e2e - 构建后运行端到端测试（启动真实服务，包括无头浏览器）

故障排除

身份验证问题

• 如果二维码未显示，请尝试重启服务
• 如果已通过身份验证，则不会显示二维码（使用 check_auth_status 验证）
• 如果需要重新进行身份验证，请先使用 logout 工具，然后请求新的二维码
• WhatsApp 对已关联设备的数量有限制；你可能需要移除一台已有设备
• 如果收到“No QR code is currently available”消息，但你已经通过身份验证，这是正常情况——使用 check_auth_status 确认身份验证状态

连接问题

• 确保网络连接稳定
• 如果连接失败，请尝试重启服务
• 查看日志以获取详细错误消息

浏览器进程问题

• 如果发现 CPU 使用率或内存占用过高，可能存在孤立的 Chrome 进程
• 运行 npm run cleanup-browsers 检测并清理孤立进程
• 如果服务频繁崩溃，请检查并清理孤立进程
• 在 Windows 上，也可以使用任务管理器查找命令行中包含“headless”的多个 Chrome 进程
• 在 Linux/macOS 上，使用 ps aux | grep chrome 检查是否存在孤立进程

许可证

MIT

---

此项目是原始 whatsapp-mcp 的 TypeScript 移植版，原作者为 lharries。