WhatsApp-MCP2

Name: WhatsApp-MCP2
Author: fyimail

作者：fyimail6 星标更新：2025-04-25

安装使用来源：spider==github.com

项目介绍

WhatsApp Web MCP

一款强大的桥梁，通过模型上下文协议（MCP）连接WhatsApp Web与AI模型。该项目使AI模型如Claude能够通过标准化接口与WhatsApp进行交互，从而轻松地以编程方式自动化和增强WhatsApp互动。

概述

WhatsApp Web MCP通过以下方式实现了WhatsApp Web与AI模型之间的无缝集成：

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

免责声明

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

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

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

安装

克隆仓库：

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

全局安装或使用npx：

# 全局安装
npm install -g .

# 或直接使用npx
npx .

使用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密钥: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

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

npx wweb-mcp --mode mcp --mcp-mode api --api-base-url http://localhost:3[...]

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`（查询参数）: 消息数量
`/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`（查询参数）: 消息数量
`/api/groups/{groupId}/participants/add`	POST	向群组添加成员	`participants`: 电话号码数组
`/api/groups/send`	POST	向群组发送消息	`groupId`: 群组ID<br>`message`: 消息内容

AI集成

Claude桌面集成

选项1：使用NPX

启动WhatsApp API服务器：
```
npx wweb-mcp -m whatsapp-api -s local
```
使用您的WhatsApp移动应用扫描二维码

记录日志中显示的API密钥：

WhatsApp API密钥: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

在您的Claude桌面配置中添加以下内容：

{
    "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

在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

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

记录日志中显示的API密钥：

WhatsApp API密钥: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

在您的Claude桌面配置中添加以下内容：

{
    "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"
            ]
        }
    }
}

重新启动Claude桌面
WhatsApp功能将通过Claude界面可用

架构

该项目具有清晰的关注点分离结构：

组件

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

部署选项

WhatsApp API服务器: 独立的REST API服务器
MCP服务器（独立）: 直接连接到WhatsApp Web
MCP服务器（API客户端）: 连接到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

代码检查和格式化

该项目使用ESLint和Prettier进行代码质量和格式化：

# 运行代码检查器
npm run lint

# 自动修复代码检查问题
npm run lint:fix

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

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

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

故障排除

Claude桌面集成问题

无法在Claude中以命令独立模式启动wweb-mcp，因为Claude会多次打开多个进程，而每个wweb-mcp都需要打开一个puppeteer会话，这些会话不能共享相同的WhatsApp认证。由于这个限制，我们已将应用程序拆分为MCP和API模式，以允许与Claude的正确集成。

即将推出的功能

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

贡献

分叉仓库
创建功能分支
提交更改
推送到您的分支
创建Pull Request

请确保您的PR：

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

依赖项

WhatsApp Web.js

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

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

日志

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

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

日志级别

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

error - 阻止应用程序运行的关键错误
warn - 不阻止应用程序但需要关注的警告
info - 关于应用程序状态和事件的一般信息
http - HTTP请求/响应日志
debug - 详细的调试信息

配置日志级别

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

npm start -- --log-level=debug

或者在全局安装时使用：

wweb-mcp --log-level=debug

命令模式日志

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

测试环境

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