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

概述

此项目是一个基于 Node.js 的单进程应用程序，主要用于连接 WhatsApp Web API 并提供 MCP（Model Context Protocol）服务。以下是其主要功能和技术架构：

1. 核心组件：

   • 使用 @whiskeysockets/baileys 库与 WhatsApp Web API 通信。
   • 使用 SQLite 数据库存储消息和聊天记录。
   • 基于 MCP 协议提供标准输入输出接口，供 AI 客户端调用。

2. 技术栈：

   • 开发语言：TypeScript
   • 运行时环境：Node.js（版本 23.10.0 及以上）
   • 数据库：SQLite（通过 node:sqlite 库实现）
   • 日志记录：Pino
   • 参数验证：Zod

功能特性

• 认证管理：

  • 使用 Baileys 库处理 WhatsApp 账号的登录和认证。
  • 支持扫描 QR 码进行初始登录，以及后续的自动重连。

• 数据存储：

  • 所有聊天记录、消息内容及元数据均存储在本地 SQLite 数据库中（路径为 ./data/whatsapp.db）。
  • 认证信息和敏感数据存储于 ./auth_info/ 目录，防止意外提交到版本控制系统。

• MCP 接口：

  • 提供多个 MCP 工具函数（如搜索联系人、列出聊天记录、发送消息等）。
  • 支持与 AI 客户端（如 Claude Desktop 或 Cursor）集成，通过标准输入输出交互。

使用说明

1. 环境要求

• Node.js 版本：23.10.0 及以上
• 安装依赖：

  npm install
  

2. 启动服务器

运行以下命令启动 MCP 服务：

node src/main.ts

首次启动时，程序会生成 QR 码链接并在控制台输出。使用手机扫描该链接完成登录。

3. 配置 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"
      }
    ]
  }
  

4. 使用 MCP 工具

在 AI 客户端中调用以下工具：

• searchContacts：搜索联系人。
• listChats：列出最近聊天记录。
• readMessages：读取消息内容。
• sendMessage：发送新消息。

故障排除

1. QR 码问题

• 如果无法自动打开 QR 码链接，查看控制台输出获取 URL 并手动访问。
• 使用手机上的 WhatsApp 应用扫描 QR 码完成登录。

2. 登录失效

如果出现登录失效，请执行以下步骤：

1. 停止当前运行的 MCP 服务。
2. 删除 ./auth_info/ 目录下的所有文件。
3. 重新启动服务并完成新的 QR 码扫描流程。

3. 数据库问题

• 如果 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 应用程序中。希望这份指南能帮助您顺利部署和使用该服务。