🚀 WhatsApp MCP 服务器使用指南（中文版）
本项目是一个基于 Node.js 的单进程应用程序，主要用于连接 WhatsApp Web API 并提供 MCP（Model Context Protocol）服务，帮助开发者便捷地与 WhatsApp 服务交互，并集成到 AI 应用程序中。
✨ 主要特性
- 认证管理：借助 Baileys 库处理 WhatsApp 账号的登录与认证，支持扫描 QR 码进行初始登录，后续还能自动重连。
- 数据存储：所有聊天记录、消息内容及元数据都存于本地 SQLite 数据库（路径为
./data/whatsapp.db），认证信息和敏感数据存于./auth_info/目录，避免意外提交到版本控制系统。 - MCP 接口：提供多个 MCP 工具函数（如搜索联系人、列出聊天记录、发送消息等），支持与 AI 客户端（如 Claude Desktop 或 Cursor）通过标准输入输出进行交互。
📦 安装指南
环境要求
- Node.js 版本：23.10.0 及以上
- 安装依赖：
npm install
🚀 快速开始
启动服务器
运行以下命令启动 MCP 服务：
node src/main.ts
首次启动时，程序会生成 QR 码链接并在控制台输出，使用手机扫描该链接完成登录。
配置 AI 客户端
对于 Claude Desktop
- 创建配置文件
claude_desktop_config.json：
{
"servers": [
{
"name": "whatsapp",
"command": "node",
"args": ["{{PROJECT_PATH}}/src/main.ts"],
"stdio": "pipe"
}
]
}
- 替换
{{PROJECT_PATH}}为实际项目路径。
对于 Cursor
- 创建配置文件
mcp.json：
{
"servers": [
{
"name": "whatsapp",
"command": "node",
"args": ["{{PROJECT_PATH}}/src/main.ts"],
"stdio": "pipe"
}
]
}
使用 MCP 工具
在 AI 客户端中调用以下工具：
searchContacts：搜索联系人。listChats：列出最近聊天记录。readMessages：读取消息内容。sendMessage：发送新消息。
🔧 技术细节
核心组件
- 使用
@whiskeysockets/baileys库与 WhatsApp Web API 通信。 - 使用 SQLite 数据库存储消息和聊天记录。
- 基于 MCP 协议提供标准输入输出接口，供 AI 客户端调用。
技术栈
- 开发语言：TypeScript
- 运行时环境：Node.js（版本 23.10.0 及以上）
- 数据库：SQLite（通过
node:sqlite库实现） - 日志记录：Pino
- 参数验证：Zod
📚 详细文档
故障排除
QR 码问题
- 如果无法自动打开 QR 码链接，查看控制台输出获取 URL 并手动访问。
- 使用手机上的 WhatsApp 应用扫描 QR 码完成登录。
登录失效
如果出现登录失效，请执行以下步骤：
- 停止当前运行的 MCP 服务。
- 删除
./auth_info/目录下的所有文件。 - 重新启动服务并完成新的 QR 码扫描流程。
数据库问题
- 如果 SQLite 数据库文件损坏，可以尝试恢复或重建数据库。
- 确保项目目录下存在
data/和auth_info/文件夹。
日志记录
程序使用 Pino 库记录日志，默认输出到控制台。可以通过配置 Pino 的选项来调整日志级别和格式。
例子
import { log } from 'pino';
const logger = log({ level: 'info' });
logger.info('启动 WhatsApp MCP 服务');
参数验证
使用 Zod 库对输入参数进行严格验证，确保 API 调用的安全性和可靠性。
示例
import { z } from 'zod';
type SendMessageParams = {
text: string;
};
const validateMessage = z.object({
text: z.string().min(1)
});
async function sendMessage(params: SendMessageParams) {
const validated = await validateMessage.parseAsync(params);
// 处理消息
}
总结
此 WhatsApp MCP 服务器项目为开发者提供了强大的工具集，可以方便地与 WhatsApp 服务进行交互，并通过 MCP 协议集成到 AI 应用程序中。希望这份指南能帮助您顺利部署和使用该服务。