Whats App Mcp Server

这是一个 MCP（Model Context Protocol） 服务，可让 AI Agent（例如 Claude 或 Cursor）通过 WhatsApp 直接与你交互。它弥合了自主 AI 与手机之间的鸿沟，让你在离开电脑时也能进行运行时确认、权限请求或简单的状态更新。

• AI Agent 消息
• AI Agent 确认
• Agent 中断系统
• AI 警报
• MCP 服务
• Cursor MCP
• Claude Desktop MCP
• AI 通知

适用场景

• Cursor
• Claude Desktop
• Claude Code
• OpenCode
• Codex
• 自主 AI 工作流

示例

AI： 部署到生产环境？

WhatsApp： [是] [否]

你： 是

Agent 继续执行。

---

🚀 快速开始（NPX）

由于此软件包已发布到 NPM，你可以通过 MCP 配置中的 npx 直接运行。

Cursor / Claude 配置

将以下内容添加到你的 MCP 配置文件中：

{
  "mcpServers": {
    "whatsapp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mhrj/whatsapp-mcp"
      ],
      "env": {
        "WHATSAPP_TARGET_NUMBER": "[email protected]"
      }
    }
  }
}

关于允许的号码的说明：WHATSAPP_TARGET_NUMBER 是所有消息的默认接收方。不过，如果目标是 Whatsapp 群组，默认情况下群组中的任何成员都可以回答 AI。若要将回复限制为仅来自特定号码（防止未经授权的人回复），你可以选择添加一个以逗号分隔的号码列表作为环境变量："WHATSAPP_ALLOWED_NUMBERS": "[email protected],[email protected]"。设置后，AI 将仅接受来自这些匹配用户的回复。

故障排除：npx: executable file not found in $PATH 或 env: node: No such file or directory： 如果 IDE/Agent 提示找不到 npx 或 node，这是因为 GUI 应用（例如 Cursor）不会继承终端的 $PATH。要解决此问题，请在 MCP env 配置中显式传入你的 PATH。

      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin",
        "WHATSAPP_TARGET_NUMBER": "[email protected]"
      }

身份验证（仅首次需要）

首次使用 MCP 服务时，需要通过 WhatsApp Web 进行身份验证：

1. 通过你的 Agent 调用 connect 工具，或像平常一样使用任意 WhatsApp 工具。如果会话尚未通过身份验证，服务将自动启动身份验证。
2. 工具结果会直接在 MCP 内容中返回 QR 码图像，现代客户端可以将其内嵌显示。
3. 如果客户端无法内嵌显示图像，服务还会尝试在 ~/.whatsapp-mcp/qr.html 下写入本地备用 HTML 页面。
4. 在手机上打开 WhatsApp -> 已关联的设备 -> 关联设备，然后扫描 QR 码。
5. 身份验证会话会保存在你的主目录中（~/.whatsapp-mcp/baileys_auth_info），因此重启后无需再次扫描。

远程“自动驾驶”工作流（跳过 IDE 提示）

要让 AI Agent 完全自主运行，只通过 WhatsApp 请求许可/指导（这样你就可以离开电脑）：

1. 移除 IDE 安全拦截：当你的 Agent（如 Cursor 或 Claude）请求许可来运行命令或读取文件时，选择 Always Allow（或在设置中启用“yolo”模式）。这样 Agent 就能自由执行操作，无需一直停下来等待你点击界面。
2. 添加 .cursorrules（或系统提示词）文件：你必须明确指示 AI 在遇到需要做出判断的节点时使用 WhatsApp。在项目根目录中创建 .cursorrules 文件，并填入以下提示词：

# Human-in-the-Loop via WhatsApp
You are connected to the user via the `whatsapp-mcp` server. 
Whenever you are about to make significant/destructive changes, run a deployment, or whenever you need the user's permission/opinion to proceed with a plan, you MUST use the `ask_question` tool to ask the user on WhatsApp. 
DO NOT simply ask for confirmation in the IDE chat interface. You must wait for the `ask_question` tool to return the user's WhatsApp reply before proceeding with your task.

完成这两个步骤后，AI 就会主动主动使用 ask_question 工具，将需要逻辑判断的权限请求直接发送到你的手机，而不是卡在 IDE 中。

功能与工具

• connect：连接到 WhatsApp 网络。如果尚未登录，会在工具结果中返回原生二维码图片，也可能提供本地 HTML 备用页面。
• disconnect：完全退出 WhatsApp 并使会话凭据失效。
• send_message：发送单向通知。支持可选的 WhatsApp Markdown 映射（*bold*）。如果服务尚未连接，会自动触发身份验证。
• ask_question：发送提示词并阻塞执行，直到收到回复（或超时）。并发问题会智能排队并附上引用标记。如果服务尚未连接，会自动触发身份验证。
• get_incoming_messages：轮询收到的非请求 WhatsApp 消息，让不支持服务端采样的 Agent 也能获取这些消息。
• get_status：监控 Agent 的连接状态，包括 connected、connecting 或 qr_pending 等身份验证状态。
• 服务端说明 + 提示词：服务会导出内置工作流说明和 whatsapp-autopilot 提示词，帮助客户端引导 Agent 优先连接并优先使用 WhatsApp。

本地开发

如果你想从源代码在本地运行：

1. 克隆代码库并运行 npm install
2. 运行 npm run build
3. 使用绝对路径链接，而不是使用 npx。

许可证

本项目采用 ISC License 授权。

第三方许可证

本项目使用了以下开源库：

• @modelcontextprotocol/sdk - MIT License
• @whiskeysockets/baileys - MIT License
• 其他依赖项（express、pino、qrcode 等）均采用宽松许可证（MIT/BSD）授权。

---

便于发现的关键词

• 人在回路中的 AI
• AI 审批
• 运行时审批
• Agent 通知
• Agent 审批工作流
• Cursor WhatsApp 集成
• Claude WhatsApp 集成
• 自主 Agent
• Cursor 高级用户
• 远程工作者

这解决了什么问题？

• 当你离开 IDE 时，AI Agent 经常会因等待审批/问题答复而停滞。
• WhatsApp MCP 会向你发送通知，并通过手机收集确认信息，让 Agent 能够安全地继续工作。

适用对象

• Cursor Agent / Claude Desktop 用户
• 构建并交付 Agent 工作流的独立开发者
• 需要运行时审批的 DevOps 和自动化团队