DotAgents WhatsApp MCP 服务器

使用说明（Markdown 格式）

• 项目简介

  • 该仓库包含一个基于 MCP 的服务器实现，专门把 WhatsApp 的消息收发能力暴露给 MCP 客户端。通过工具调用的方式，MCP 客户端可以向服务器发送指令（如发送消息、获取会话记录、列出会话等），服务器执行相应操作并返回标准化的 JSON-RPC 响应。

• 主要功能点

  • MCP 协议核心能力：实现 ListTools 与 CallTool 两类核心请求，按照 MCP 的 JSON-RPC 约定返回结果。
  • WhatsApp 会话管理：使用 Baileys 库连接 WhatsApp，处理连接、认证、消息上报与媒体下载等。
  • 工具实现与暴露：提供 whatsapp_send_message、whatsapp_get_messages、whatsapp_list_chats、whatsapp_get_pending_messages、whatsapp_connect、whatsapp_disconnect、whatsapp_logout、whatsapp_send_typing 等工具接口，供 MCP 客户端调用。
  • 回调转发与自动回复：在配置 callbackUrl / callbackApiKey 时，将接收到的消息转发到回调端点，并在配置开启时自动回复。
  • 会话路由与队列化处理：对同一聊天进行串行处理，维护活跃对话、会话持久化、并在需要时持久化会话状态。
  • 会话上下文与持久化：对活跃会话进行持久化、保存对话历史和会话标识，便于重启后恢复。

• 安装步骤

  • 请确保本机安装了 Node.js 18 及以上版本。
  • 将仓库克隆到本地，进入该子模块目录，安装依赖：
    • 使用 pnpm 安装（推荐）或 npm/yarn 安装依赖。
  • 构建与运行 MCP 服务器：
    • 运行环境变量配置（如 WhatsApp 认证目录、回调地址等，可按需要设置）。
    • 构建服务器代码（使用 tsup 配置进行打包）。
    • 启动服务器（生成的可执行入口或 dist/index.js，由构建产物决定）。

• 服务器配置（MCP 客户端需要用于连接该 MCP 服务器的启动命令和参数）

  • 服务器名称：whatsapp
  • 启动命令与参数示例（JSON 形式，描述性说明如下；MCP 客户端不需要额外代码）： { "mcpServers": { "whatsapp": { "name": "whatsapp", "command": "npx", "args": ["@dotagents/mcp-whatsapp"] } } } 说明：
  • name: 服务器注册的名称，应与实现中的服务器标识保持一致。
  • command: 启动该 MCP 服务器所需的命令（如 npx），用于在 MCP 客户端托管时启动服务器进程。
  • args: 启动参数数组，若使用 NPM/Yarn 包执行，请按实际安装的包名称配置。该示例对应仓库中的 mcp-whatsapp 包。

• 基本使用方法

  • MCP 客户端通过 JSON-RPC 请求调用该服务器暴露的工具，例如列出支持的工具、调用具体工具实现发送消息、获取会话历史等。
  • 使用前请确保 WhatsApp 认证所需的凭据已配置（authDir 等环境变量），并在需要时设置回调地址以实现消息转发。
  • 如需持续运行，请确保 WhatsApp 连接凭据正确保存，且服务器具备重连策略。