WhatsApp MCP Server (TypeScript/Baileys)

WhatsApp MCP 服务（TypeScript/Baileys）

这是一个适用于 WhatsApp 的模型上下文协议（MCP）服务，使用 TypeScript 构建，并采用 @whiskeysockets/baileys 库。

它可以将你的个人 WhatsApp 账号连接到 AI Agent（例如通过桌面应用使用的 Anthropic Claude 或 Cursor），让其能够：

• 搜索你的个人 WhatsApp 消息。
• 搜索你的联系人（个人联系人，不包括群组）。
• 列出你最近的聊天。
• 获取特定聊天的消息历史记录。
• 向个人或群组发送消息。

它使用 WhatsApp Web 多设备 API，直接连接到你的个人 WhatsApp 账号。所有消息和身份验证信息都存储在本地 SQLite 数据库（./data/）和身份验证缓存（./auth_info/）中。只有当你连接的 AI Agent 明确调用所提供的 MCP 工具时，数据才会发送给该 Agent（你可以通过 Agent 的界面控制这一点）。

（可选：可以考虑在此处添加类似参考示例的屏幕截图或 GIF）

示例

用户： 在 WhatsApp 中给“Meu amor”发送消息“Te amo”

---

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

{
  "query": "Meu amor"
}

---

工具结果：

[
  {
    "jid": "[email protected]",
    "name": "Meu Amor"
  }
]

---

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

{
  "recipient": "[email protected]",
  "message": "Te amo"
}

---

工具结果：

Message sent successfully to [email protected] (ID: XXXXXXXXXXX).

主要功能（MCP 工具）

该服务向连接的 AI Agent 提供以下工具：

• search_contacts：按姓名或部分电话号码（JID）搜索联系人。
• list_messages：获取特定聊天的消息历史记录，支持分页。
• list_chats：列出你的聊天，可按活跃度或名称排序、筛选和分页，并可选择包含最后一条消息的详情。
• get_chat：获取特定聊天的详细信息。
• get_message_context：获取特定消息 ID 前后紧邻发送的消息，以提供上下文。
• send_message：向指定的接收者 JID（用户或群组）发送文本消息。

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 WhatsApp MCP 服务：

npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude

前置条件

• 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 生成二维码链接，并尝试在默认浏览器中打开。
   • 使用 WhatsApp 手机应用扫描此二维码（设置 > 已关联设备 > 关联设备）。
   • 身份验证凭据会保存在本地的 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, // Optional: Adjust startup timeout if needed
         "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 客户端后，你可以通过 Agent 的聊天界面与 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 套接字发送消息。
5. 使用 pino 记录活动（WhatsApp 事件记录在 wa-logs.txt 中，MCP 服务活动记录在 mcp-logs.txt 中）。

数据存储与隐私

• 身份验证： WhatsApp 连接凭据存储在本地 ./auth_info/ 目录中。
• 消息与聊天： 消息历史记录和聊天元数据存储在本地 SQLite 文件 ./data/whatsapp.db 中。
• 本地数据： auth_info/ 和 data/ 均列在 .gitignore 中，以防止意外提交。请将这些目录视为敏感数据。
• 与大模型交互： 只有当 AI Agent 主动使用某个 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 工具输入）

故障排除

• 二维码问题：
  • 如果二维码链接未自动打开，请检查控制台输出中的 quickchart.io URL，并手动打开。
  • 请确保及时使用手机上的 WhatsApp 应用扫描二维码。
• 身份验证失败／已退出登录：
  • 如果连接因 DisconnectReason.loggedOut 错误而关闭，则需要重新进行身份验证。停止服务，删除 ./auth_info/ 目录，然后重启服务（node src/main.ts）以获取新二维码。
• 消息同步问题：
  • 初次同步可能需要一些时间。请检查 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 正确（例如，用户使用 [email protected]，群组使用 [email protected]）。
  • 检查 wa-logs.txt 中 Baileys 报告的具体错误。
• 一般问题： 检查 wa-logs.txt 和 mcp-logs.txt，查看详细的错误消息。

如需解决更多 MCP 集成问题，请参阅 MCP 官方文档。

致谢

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

许可证

本项目采用 ISC 许可证授权（参见 package.json）。