WhatsApp MCP 服务器 (TypeScript/Baileys)

这是一个 WhatsApp 的模型上下文协议 (MCP) 服务器，使用 TypeScript 构建，并使用 @whiskeysockets/baileys 库。

它允许您将您的个人 WhatsApp 帐户连接到 AI 代理（例如通过其桌面应用程序或 Cursor 连接的 Anthropic Claude），使其能够：

• 搜索您的个人 WhatsApp 消息。
• 搜索您的联系人（个人，而不是群组）。
• 列出您最近的聊天记录。
• 检索特定聊天记录的消息历史。
• 向个人或群组发送消息。

它使用 WhatsApp Web 多设备 API 直接连接到您的个人 WhatsApp 帐户。 您的所有消息和身份验证详细信息都本地存储在 SQLite 数据库 (./data/) 和身份验证缓存 (./auth_info/) 中。 只有当连接的 AI 代理明确使用提供的 MCP 工具时（您可以通过代理的界面控制），数据才会发送到该代理。

(可选：考虑添加类似于此处参考示例的屏幕截图或 GIF)

示例

用户： 发送一条 whatsapp 消息给 whatsapp 中的 "Meu amor"，内容为 "Te amo"

---

助手： 好的，我需要先找到联系人。 使用工具：whatsapp.search_contacts

{
  "query": "Meu amor"
}

---

工具结果：

[
  {
    "jid": "5599xxxxxx@s.whatsapp.net",
    "name": "Meu Amor"
  }
]

---

助手： 找到联系人。 现在发送消息。 使用工具：whatsapp.send_message

{
  "recipient": "5599xxxxxx@s.whatsapp.net",
  "message": "Te amo"
}

---

工具结果：

消息已成功发送至 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX)。

主要功能 (MCP 工具)

服务器向连接的 AI 代理公开以下工具：

• search_contacts: 按姓名或电话号码部分 (JID) 搜索联系人。
• list_messages: 检索特定聊天的消息历史记录，带有分页。
• list_chats: 列出您的聊天记录，可按活动或名称排序，可过滤，分页，可选地包括最后一条消息的详细信息。
• get_chat: 获取有关特定聊天的详细信息。
• get_message_context: 检索特定消息 ID 前后立即发送的消息以获取上下文。
• send_message: 向指定的收件人 JID（用户或群组）发送文本消息。

安装

前提条件

• Node.js: 23.10.0 或更高版本（如 package.json 中指定）。 您可以使用 node -v 检查您的版本。（具有初始 typescript 和 sqlite 内置支持）
• npm（或 yarn/pnpm）：通常与 Node.js 一起提供。
• AI 客户端： Anthropic Claude Desktop 应用程序、Cursor、Cline 或 Roo Code（或其他 MCP 兼容客户端）。

步骤

1. 克隆此存储库：

   git clone <your-repo-url> whatsapp-mcp-ts
   cd whatsapp-mcp-ts
   

2. 安装依赖项：

   npm install
   # or yarn install / pnpm install
   

3. 首次运行服务器： 使用 node 直接运行主脚本。

   node src/main.ts
   

   • 首次运行时，它可能会使用 quickchart.io 生成一个 QR 代码链接，并尝试在您的默认浏览器中打开它。
   • 使用您的 WhatsApp 移动应用程序扫描此 QR 代码（设置 > 关联设备 > 关联设备）。
   • 身份验证凭据将本地保存在 auth_info/ 目录中（此目录被 git 忽略）。
   • 消息将开始同步并存储在 ./data/whatsapp.db 中。 这可能需要一些时间，具体取决于您的历史记录大小。 检查 wa-logs.txt 和控制台输出以了解进度。
   • 保持此终端窗口运行。 同步后您可以关闭。

AI 客户端的配置

您需要告诉您的 AI 客户端如何启动此 MCP 服务器。

1. 准备配置 JSON： 复制以下 JSON 结构。 您需要将 {{PATH_TO_REPO}} 替换为您克隆此存储库的目录的绝对路径。

   {
     "mcpServers": {
       "whatsapp": {
         "command": "node",
         "args": [
           "{{PATH_TO_REPO}}/src/main.ts"
         ],
         "timeout": 15, // 可选：如果需要，调整启动超时
         "disabled": false
       }
     }
   }
   

   • 获取绝对路径： 在您的终端中导航到 whatsapp-mcp-ts 目录并运行 pwd。 使用此输出作为 {{PATH_TO_REPO}}。

2. 保存配置文件：

   • 对于 Claude Desktop： 将 JSON 保存为 claude_desktop_config.json 在其配置目录中：
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json (可能路径，如果需要请验证)
     • Linux: ~/.config/Claude/claude_desktop_config.json (可能路径，如果需要请验证)
   • 对于 Cursor： 将 JSON 保存为 mcp.json 在其配置目录中：
     • ~/.cursor/mcp.json

3. 重启 Claude Desktop / Cursor： 关闭并重新打开您的 AI 客户端。 它现在应该检测到 "whatsapp" MCP 服务器，并允许您使用其工具。

用法

一旦服务器正在运行（通过 node src/main.ts 手动运行，或由 AI 客户端通过配置文件启动）并连接到您的 AI 客户端，您就可以通过代理的聊天界面与您的 WhatsApp 数据进行交互。 要求它搜索联系人、列出最近的聊天记录、阅读消息或发送消息。

架构概述

此应用程序是一个单独的 Node.js 进程，它：

1. 使用 @whiskeysockets/baileys 连接到 WhatsApp Web API，处理身份验证和实时事件。
2. 使用 node:sqlite 将 WhatsApp 聊天记录和消息本地存储在 SQLite 数据库 (./data/whatsapp.db) 中。
3. 使用 @modelcontextprotocol/sdk 运行一个 MCP 服务器，该服务器通过标准输入/输出 (stdio) 侦听来自 AI 客户端的请求。
4. 提供 MCP 工具，这些工具查询本地 SQLite 数据库或使用 Baileys socket 发送消息。
5. 使用 pino 记录活动（wa-logs.txt 用于 WhatsApp 事件，mcp-logs.txt 用于 MCP 服务器活动）。

数据存储与隐私

• 身份验证： 您的 WhatsApp 连接凭据本地存储在 ./auth_info/ 目录中。
• 消息和聊天记录： 您的消息历史记录和聊天元数据本地存储在 ./data/whatsapp.db SQLite 文件中。
• 本地数据： auth_info/ 和 data/ 都包含在 .gitignore 中，以防止意外提交。 将这些目录视为敏感目录。
• LLM 交互： 只有当 AI 代理主动使用提供的 MCP 工具之一时（例如，list_messages、send_message），数据才会发送到连接的大型语言模型 (LLM)。 服务器本身不会主动将您的数据发送到其他任何地方。

技术细节

• 语言： TypeScript
• 运行时： Node.js (>= v23.10.0)
• WhatsApp API： @whiskeysockets/baileys
• MCP SDK： @modelcontextprotocol/sdk
• 数据库： node:sqlite (捆绑的 SQLite)
• 日志记录： pino
• 模式验证： zod (用于 MCP 工具输入)

故障排除

• QR 码问题：
  • 如果 QR 码链接没有自动打开，请检查控制台输出中的 quickchart.io URL 并手动打开它。
  • 确保您使用手机的 WhatsApp 应用程序及时扫描 QR 码。
• 身份验证失败/已注销：
  • 如果连接因 DisconnectReason.loggedOut 错误而关闭，您需要重新进行身份验证。 停止服务器，删除 ./auth_info/ 目录，然后重新启动服务器 (node src/main.ts) 以获取新的 QR 码。
• 消息同步问题：
  • 初始同步可能需要一些时间。 检查 wa-logs.txt 以了解活动。
  • 如果消息似乎不同步或丢失，您可能需要完全重置。 停止服务器，删除两个 ./auth_info/ 和 ./data/ 目录，然后重新启动服务器以重新进行身份验证并重新同步历史记录。
• MCP 连接问题 (Claude/Cursor)：
  • 仔细检查您的 claude_desktop_config.json 或 mcp.json 中的 command 和 args（尤其是 {{PATH_TO_REPO}}）。 确保路径是绝对路径且正确。
  • 验证 Node.js 是否已正确安装并在您的系统 PATH 中。
  • 检查 AI 客户端的日志中是否存在与启动 MCP 服务器相关的错误。
  • 检查此服务器的日志 (mcp-logs.txt) 中是否存在与 MCP 相关的错误。
• 发送消息时出错：
  • 确保收件人 JID 正确（例如，number@s.whatsapp.net 用于用户，groupid@g.us 用于群组）。
  • 检查 wa-logs.txt 中是否存在来自 Baileys 的特定错误。
• 一般问题： 检查 wa-logs.txt 和 mcp-logs.txt 以获取详细的错误消息。

有关更多 MCP 集成问题，请参阅官方 MCP 文档。

鸣谢

• https://github.com/lharries/whatsapp-mcp 与此代码库相同，但使用 go 和 python。

许可证

本项目根据 ISC 许可证获得许可（请参阅 package.json）。