🚀 WhatsApp MCP 服务器使用指南（中文版）

本项目是一个基于 Node.js 的单进程应用程序，主要用于连接 WhatsApp Web API 并提供 MCP（Model Context Protocol）服务，为开发者与 WhatsApp 服务交互提供便利，还能通过 MCP 协议集成到 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"
        }
    ]
}

💻 使用示例

基础用法

在 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 码完成登录。

登录失效

若出现登录失效，可按以下步骤操作：

1. 停止当前运行的 MCP 服务。
2. 删除 ./auth_info/ 目录下的所有文件。
3. 重新启动服务并完成新的 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 应用程序中。希望这份指南能帮助您顺利部署和使用该服务。