WhatsApp Web MCP

这是一个使用模型上下文协议 (MCP) 的 WhatsApp Web 和 AI 模型之间的强大桥梁。该项目使像 Claude 这样的 AI 模型能够通过标准化接口与 WhatsApp 交互，从而可以轻松地以编程方式自动化和增强 WhatsApp 交互。

概述

WhatsApp Web MCP 通过以下方式提供 WhatsApp Web 和 AI 模型之间的无缝集成：

• 通过模型上下文协议 (MCP) 创建标准化接口
• 提供对 WhatsApp 功能的 MCP 服务器访问
• 通过 SSE 或命令模式提供灵活的部署选项
• 支持直接 WhatsApp 客户端集成和基于 API 的连接

免责声明

重要提示：此工具仅用于测试目的，不应在生产环境中使用。

来自 WhatsApp Web 项目的免责声明：

本项目与 WhatsApp 或其任何子公司或附属公司没有任何关联、联系、授权、认可或以任何方式正式连接。 官方 WhatsApp 网站可以在 whatsapp.com 找到。“WhatsApp”以及相关的名称、标记、徽章和图像是其各自所有者的注册商标。 此外，不能保证您在使用此方法时不会被阻止。 WhatsApp 不允许在其平台上使用机器人或非官方客户端，因此不应认为这是完全安全的。

安装

1. 克隆存储库：

   git clone https://github.com/pnizer/wweb-mcp.git
   cd wweb-mcp
   

2. 全局安装或与 npx 一起使用：

   # 全局安装
   npm install -g .
   
   # 或直接与 npx 一起使用
   npx .
   

3. 使用 Docker 构建：

   docker build . -t wweb-mcp:latest
   

配置

命令行选项

选项	别名	描述	选择	默认值
--mode	-m	运行模式	mcp, whatsapp-api	mcp
--mcp-mode	-c	MCP 连接模式	standalone, api	standalone
--transport	-t	MCP 传输模式	sse, command	sse
--sse-port	-p	SSE 服务器端口	-	3002
--api-port	-	WhatsApp API 服务器端口	-	3001
--auth-data-path	-a	存储身份验证数据的路径	-	.wwebjs_auth
--auth-strategy	-s	身份验证策略	local, none	local
--api-base-url	-b	使用 api 模式时 MCP 的 API 基本 URL	-	http://localhost:3001/api
--api-key	-k	使用 api 模式时 WhatsApp Web REST API 的 API 密钥	-	''

API 密钥身份验证

在 API 模式下运行时，WhatsApp API 服务器需要使用 API 密钥进行身份验证。 API 密钥在您启动 WhatsApp API 服务器时自动生成，并显示在日志中：

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

要将 MCP 服务器连接到 WhatsApp API 服务器，您需要使用 --api-key 或 -k 选项提供此 API 密钥：

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

API 密钥存储在身份验证数据目录（由 --auth-data-path 指定）中，并在 WhatsApp API 服务器重启后仍然存在。

身份验证方法

本地身份验证（推荐）

• 扫描二维码一次
• 凭据在会话之间保持不变
• 对于长期运行更稳定

无身份验证

• 默认方法
• 每次启动都需要扫描二维码
• 适用于测试和开发

用法

运行模式

WhatsApp API 服务器

运行一个独立的 WhatsApp API 服务器，该服务器通过 REST 端点公开 WhatsApp 功能：

npx wweb-mcp --mode whatsapp-api --api-port 3001

MCP 服务器（独立）

运行直接连接到 WhatsApp Web 的 MCP 服务器：

npx wweb-mcp --mode mcp --mcp-mode standalone --transport sse --sse-port 3002

MCP 服务器（API 客户端）

运行连接到 WhatsApp API 服务器的 MCP 服务器：

# 首先，启动 WhatsApp API 服务器并从日志中记下 API 密钥
npx wweb-mcp --mode whatsapp-api --api-port 3001

# 然后，使用 API 密钥启动 MCP 服务器
npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY --transport sse --sse-port 3002

可用工具

工具	描述	参数
get_status	检查 WhatsApp 客户端连接状态	无
send_message	向 WhatsApp 联系人发送消息	number: 要发送到的电话号码<br>message: 要发送的文本内容
search_contacts	按姓名或号码搜索联系人	query: 用于查找联系人的搜索词
get_messages	从特定聊天中检索消息	number: 要从中获取消息的电话号码<br>limit (可选): 要检索的消息数量
get_chats	获取所有 WhatsApp 聊天的列表	无
create_group	创建新的 WhatsApp 群组	name: 群组名称<br>participants: 要添加的电话号码数组
add_participants_to_group	将参与者添加到现有群组	groupId: 群组 ID<br>participants: 要添加的电话号码数组
get_group_messages	从群组中检索消息	groupId: 群组 ID<br>limit (可选): 要检索的消息数量
send_group_message	向群组发送消息	groupId: 群组 ID<br>message: 要发送的文本内容
search_groups	按名称、描述或成员名称搜索群组	query: 用于查找群组的搜索词
get_group_by_id	获取有关特定群组的详细信息	groupId: 要获取的群组 ID

可用资源

资源 URI	描述
whatsapp://contacts	所有 WhatsApp 联系人的列表
whatsapp://messages/{number}	来自特定聊天的消息
whatsapp://chats	所有 WhatsApp 聊天的列表
whatsapp://groups	所有 WhatsApp 群组的列表
whatsapp://groups/search	按名称、描述或成员名称搜索群组
whatsapp://groups/{groupId}/messages	来自特定群组的消息

REST API 端点

联系人和消息

端点	方法	描述	参数
/api/status	GET	获取 WhatsApp 连接状态	无
/api/contacts	GET	获取所有联系人	无
/api/contacts/search	GET	搜索联系人	query: 搜索词
/api/chats	GET	获取所有聊天	无
/api/messages/{number}	GET	从聊天中获取消息	limit (query): 消息数量
/api/send	POST	发送消息	number: 接收者<br>message: 消息内容

群组管理

端点	方法	描述	参数
/api/groups	GET	获取所有群组	无
/api/groups/search	GET	搜索群组	query: 搜索词
/api/groups/create	POST	创建新群组	name: 群组名称<br>participants: 数字数组
/api/groups/{groupId}	GET	获取有关特定群组的详细信息	无
/api/groups/{groupId}/messages	GET	从群组中获取消息	limit (query): 消息数量
/api/groups/{groupId}/participants/add	POST	将成员添加到群组	participants: 数字数组
/api/groups/send	POST	向群组发送消息	groupId: 群组 ID<br>message: 消息内容

AI 集成

Claude Desktop 集成

选项 1：使用 NPX

1. 启动 WhatsApp API 服务器：

   npx wweb-mcp -m whatsapp-api -s local
   

2. 使用您的 WhatsApp 移动应用扫描二维码

3. 记下日志中显示的 API 密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
   

4. 将以下内容添加到您的 Claude Desktop 配置中：

   {
       "mcpServers": {
           "whatsapp": {
               "command": "npx",
               "args": [
                   "wweb-mcp",
                   "-m", "mcp",
                   "-s", "local",
                   "-c", "api",
                   "-t", "command",
                   "--api-base-url", "http://localhost:3001/api",
                   "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
               ]
           }
       }
   }
   

选项 2：使用 Docker

1. 在 Docker 中启动 WhatsApp API 服务器：

   docker run -i -p 3001:3001 -v wweb-mcp:/wwebjs_auth --rm wweb-mcp:latest -m whatsapp-api -s local -a /wwebjs_auth
   

2. 使用您的 WhatsApp 移动应用扫描二维码

3. 记下日志中显示的 API 密钥：

   WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
   

4. 将以下内容添加到您的 Claude Desktop 配置中：

   {
       "mcpServers": {
           "whatsapp": {
               "command": "docker",
               "args": [
                   "run",
                   "-i",
                   "--rm",
                   "wweb-mcp:latest",
                   "-m", "mcp",
                   "-s", "local",
                   "-c", "api",
                   "-t", "command",
                   "--api-base-url", "http://host.docker.internal:3001/api",
                   "--api-key", "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
               ]
           }
       }
   }
   

5. 重新启动 Claude Desktop

6. WhatsApp 功能将通过 Claude 的界面提供

架构

该项目结构清晰，关注点分离：

组件

1. WhatsAppService: 与 WhatsApp 交互的核心业务逻辑
2. WhatsAppApiClient: 用于连接到 WhatsApp API 的客户端
3. API Router: REST API 的 Express 路由
4. MCP Server: 模型上下文协议实现

部署选项

1. WhatsApp API Server: 独立的 REST API 服务器
2. MCP Server (Standalone): 直接连接到 WhatsApp Web
3. MCP Server (API Client): 连接到 WhatsApp API 服务器

这种架构允许灵活的部署方案，包括：

• 在不同的机器上运行 API 服务器和 MCP 服务器
• 使用 MCP 服务器作为现有 API 服务器的客户端
• 在单台机器上运行所有内容以简化操作

开发

项目结构

src/
├── whatsapp-client.ts     # WhatsApp Web 客户端实现
├── whatsapp-service.ts    # 核心业务逻辑
├── whatsapp-api-client.ts # WhatsApp API 的客户端
├── api.ts                 # REST API 路由器
├── mcp-server.ts          # MCP 协议实现
└── main.ts                # 应用程序入口点

从源代码构建

npm run build

测试

该项目使用 Jest 进行单元测试。 要运行测试：

# 运行所有测试
npm test

# 在开发期间以监视模式运行测试
npm run test:watch

# 生成测试覆盖率报告
npm run test:coverage

Linting 和格式化

该项目使用 ESLint 和 Prettier 来保证代码质量和格式：

# 运行 linter
npm run lint

# 自动修复 linting 问题
npm run lint:fix

# 使用 Prettier 格式化代码
npm run format

# 验证代码（lint + 测试）
npm run validate

linting 配置强制执行 TypeScript 最佳实践，并在整个项目中保持一致的代码风格。

故障排除

Claude Desktop 集成问题

• 无法在 Claude 上以命令独立模式启动 wweb-mcp，因为 Claude 会多次打开多个进程，并且每个 wweb-mcp 都需要打开一个 puppeteer 会话，该会话无法共享相同的 WhatsApp 身份验证。 由于此限制，我们将应用程序拆分为 MCP 和 API 模式，以便与 Claude 正确集成。

即将推出的功能

• 为传入消息和其他 WhatsApp 事件创建 Webhook
• 支持发送媒体文件（图像、音频、文档）
• 群聊管理功能
• 联系人管理（添加/删除联系人）
• 常见场景的消息模板
• 增强的错误处理和恢复

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到您的分支
5. 创建一个 Pull Request

请确保您的 PR：

• 遵循现有的代码风格
• 包括适当的测试
• 根据需要更新文档
• 详细描述更改

依赖项

WhatsApp Web.js

该项目使用 whatsapp-web.js，这是一个非官方的 JavaScript 客户端库，用于通过 WhatsApp Web 浏览器应用程序连接 WhatsApp Web。 有关更多信息，请访问 whatsapp-web.js GitHub 存储库。

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

日志记录

WhatsApp Web MCP 包含一个使用 Winston 构建的强大的日志记录系统。 日志记录系统提供：

• 多个日志级别（error、warn、info、http、debug）
• 带有彩色日志的控制台输出
• API 端点的 HTTP 请求/响应日志记录
• 结构化错误处理
• 环境感知的日志级别（开发与生产）
• 在 MCP 命令模式下运行时，所有日志都定向到 stderr

日志级别

该应用程序支持以下日志级别，按详细程度排序：

1. error - 阻止应用程序运行的严重错误
2. warn - 不会停止应用程序但需要注意的警告
3. info - 有关应用程序状态和事件的常规信息
4. http - HTTP 请求/响应日志记录
5. debug - 详细的调试信息

配置日志级别

您可以使用 --log-level 或 -l 标志在启动应用程序时配置日志级别：

npm start -- --log-level=debug

或者在使用全局安装时：

wweb-mcp --log-level=debug

命令模式日志记录

在 MCP 命令模式 (--mode mcp --transport command) 下运行时，所有日志都定向到 stderr。 这对于命令行工具非常重要，在命令行工具中，stdout 可能用于数据输出，而 stderr 用于日志记录和诊断。 这确保了通过 stdout 的 MCP 协议通信不会受到日志消息的干扰。

测试环境

在测试环境中（当 NODE_ENV=test 时或在使用 Jest 运行时），记录器会自动调整其行为以适应测试环境。