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

article

README

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

whatsapp-mcp-ts