金大哥 - mcp-whatsapp-web MCP 详情

article

README

🚀 使用MCP WhatsApp接口

MCP WhatsApp是一个轻量级的控制台接口，可与WhatsApp Web交互。它支持用户通过命令行或集成到其他应用中收发消息，还提供了一系列管理和操作WhatsApp账户的工具。

🚀 快速开始

想要使用MCP WhatsApp 接口，可按以下步骤操作：

初始化一个新的项目并添加以下内容到package.json中：

{
  "name": "whatsapp-bot",
  "version": "1.0.0",
  "scripts": {
    "start": "mcp whatsapp:start"
  },
  "dependencies": {
    "whatsapp-mcp": "^3.0.0",
    "puppeteer": "^20.14.3"
  }
}

创建一个新的启动脚本src/index.ts：

import { start } from 'whatsapp-mcp';

start();

启动项目：
```
npm run start
```

✨ 主要特性

1. CPU占用率最低

使用Puppeteer的无头模式运行，以最小化资源消耗。

2. 跨平台兼容性

支持Windows、macOS和Linux系统。

3. 高可用性

内置断线重连机制，确保长时间稳定运行。

📦 安装指南

在开始使用之前，请确保安装了以下依赖项：

npm install puppeteer whatsapp-mcp --save

💻 使用示例

基础用法

以下是初始化whatsapp-mcp实例并发送认证请求的示例：

import { createClient } from 'whatsapp-mcp';

const client = await createClient({
  session: './session',
  headless: true,
  chromiumArgs: ['--no-sandbox', '--disable-gpu']
});

await client.auth.sendQRCode();

高级用法

以下是处理用户输入的认证令牌并确认认证状态的示例：

await client.auth.handleAuthResponse('your_auth_token_here');
console.log(await client.auth.getStatus());
// 输出: { isAuth: true, message: '已认证' }

📚 详细文档

认证流程

初始化一个新的whatsapp-mcp实例。
发送认证请求。
处理用户输入的认证令牌。
确认认证状态。

提供的工具

联系人管理

searchContacts()：通过姓名或电话号码搜索联系人。
getContactById()：获取指定联系人的详细信息。

对话管理

listChats()：列出所有可用对话及其元数据。
getChat()：获取特定对话的详细信息。
getDirectChatByContact()：查找与特定联系人的一对一聊天。

消息管理

listMessages()：按条件过滤检索消息。
sendMessage()：向指定目标发送文本或媒体消息。
listenForNewMessage()：订阅实时消息通知。

媒体处理

支持发送和接收图片、视频、文件等多媒体内容。

浏览器进程管理

无头模式运行

通过配置Puppeteer的无头参数，可以在不显示浏览器窗口的情况下运行：

await createClient({
  headless: true,
  ...
});

自动化资源清理

MCP WhatsApp在初始化时会自动优化内存使用，并在进程终止时清理临时文件。

🔧 技术细节

项目结构：默认情况下，会话数据和缓存文件存储在./session目录中。
错误处理：内置了详细的错误捕捉机制，帮助开发者快速定位问题。
日志记录：支持输出调试信息，并且允许配置不同的日志级别。

🛠️ 故障排除

1. 启动时出错

检查是否有有效的WhatsApp账户登录，或者尝试重新初始化会话文件夹：

rm -rf ./session && npm run start

2. 网络连接问题

确保网络稳定，并检查防火墙设置是否阻止了必要的端口。

📄 许可证

MCP WhatsApp是在MIT License许可证下发布的。详细许可信息请查阅项目仓库或LICENSE文件。

如需进一步帮助，请参考官方文档或通过GitHub Issues寻求支持。

mcp-whatsapp-web