WhatsApp MCP 服务器

概述

WhatsApp MCP（Model Context Protocol）服务器是一个 Node.js 应用程序，它允许通过编程方式与 macOS 上的 WhatsApp 桌面应用程序进行交互。利用 AppleScript 自动化技术，它提供了一个简单的接口用于发送消息和检查 WhatsApp 状态，而无需直接与 WhatsApp 用户界面互动。

功能

1. 向联系人发送消息

向您的 WhatsApp 联系人列表中的特定联系人发送文本消息：

• 消息通过已连接的 WhatsApp 桌面应用程序传递
• 支持包括换行在内的消息格式
• 使用 AppleScript 自动化 WhatsApp 桌面界面

2. 检查 WhatsApp 状态（开发中）

验证 WhatsApp 应用程序当前是否正在运行：

• 返回 WhatsApp 的当前运行状态
• 在尝试发送消息时帮助防止错误

3. 列出最近联系人（开发中）

由于 WhatsApp 的隐私保护措施，此功能提供了有限的功能：

• 向用户告知关于 WhatsApp 的隐私限制
• 需要准确的联系人名称以发送消息

技术实现

构建工具

• @modelcontextprotocol/sdk - MCP 服务器和 stdio 传输
• Zod - 模式验证
• Node.js 内置模块 (child_process, util, fs)
• 用于 macOS 自动化的 AppleScript

架构

• 使用 Model Context Protocol (MCP) 进行标准化工具通信
• 采用 stdio 传输方式进行通信
• 执行 AppleScript 命令与 WhatsApp 桌面应用程序交互
• 实现全面的日志记录以便调试

要求

• macOS 操作系统
• 安装了 WhatsApp 桌面应用程序
• Node.js v14.0.0 或更高版本
• 互联网连接

安装

# Clone the repository
git clone https://github.com/yourusername/whatsapp-mcp-server.git

# Navigate to the project directory
cd whatsapp-mcp-server

# Install dependencies
npm install

使用

启动服务器

node index.js

与 Claude 集成

要使 Claude 能够使用 WhatsApp MCP 服务器，请按照以下步骤操作：

1. 设置您的 MCP 服务器

   • 如上所述安装并配置 WhatsApp MCP 服务器
   • 确保服务器在本地计算机上正常运行

2. 使用您的 MCP 工具配置 Claude Desktop

   • 修改您的 claude_desktop_config.json 文件以包含 WhatsApp MCP 工具
   • 该文件通常位于您的 Claude Desktop 应用程序配置目录中
   • 添加以下配置以注册您的 WhatsApp MCP 工具：

{
  "mcpServers": [
    {
      "name": "whatsapp-mcp",
      "transport": {
        "command": "node",
        "args": ["path/to/your/index.js"]
      }
    }
  ]
}

1. 测试集成
   • 与 Claude 创建一个测试对话
   • 让 Claude 向测试联系人发送一条 WhatsApp 消息
   • 验证消息是否通过 WhatsApp 桌面应用程序成功发送

可用的 MCP 工具

1. send-whatsapp-message

向指定的 WhatsApp 联系人发送消息。

参数：

• contactName: 联系人在 WhatsApp 中显示的全名
• message: 要发送的消息内容

示例用法（通过 MCP 客户端）：

const response = await client.invoke("send-whatsapp-message", {
  contactName: "John Doe",
  message: "Hello, how are you today?"
});

2. check-whatsapp-status

检查 WhatsApp 应用程序是否当前正在运行。

不需要参数。

示例用法（通过 MCP 客户端）：

const response = await client.invoke("check-whatsapp-status", {});

3. list-recent-contacts

提供有关 WhatsApp 联系人列表的隐私限制信息。

不需要参数。

示例用法（通过 MCP 客户端）：

const response = await client.invoke("list-recent-contacts", {});

实现细节

AppleScript 自动化

服务器使用 AppleScript 来自动化 WhatsApp 桌面应用程序：

• 激活 WhatsApp 应用程序
• 使用键盘快捷键导航界面
• 按名称搜索联系人
• 使用向下箭头导航选择联系人
• 输入并发送消息

错误处理

全面的错误处理和日志记录：

• 控制台错误输出
• 在 ~/Library/Logs/whatsapp-mcp/ 中基于文件的日志记录
• 优雅处理 AppleScript 执行错误
• 进程级异常处理

使用 Claude 与 WhatsApp MCP 工具

一旦你将 WhatsApp MCP 工具与 Claude 集成，你可以使用自然语言来指示 Claude：

发送消息

示例提示：

• "给 John 发一条 WhatsApp 消息说我会晚十分钟到会"
• "在 WhatsApp 上给 Sarah 发送以下内容：这是你请求的文档"
• "在 WhatsApp 上给妈妈发 '生日快乐！'"

检查 WhatsApp 状态

示例提示：

• "我的电脑上 WhatsApp 是否在运行？"
• "检查 WhatsApp 是否处于活动状态"
• "在发送消息前验证 WhatsApp 的状态"

获取联系人信息

示例提示：

• "你能列出我最近的 WhatsApp 联系人吗？"
• "显示我在 WhatsApp 上最近联系过的人"

Claude 将根据你的请求使用相应的 MCP 工具，并提供结果反馈。

限制

• 由于依赖于 AppleScript，仅适用于 macOS
• 需要安装 WhatsApp 桌面应用程序
• 联系人选择可能会受到 WhatsApp 用户界面更改的影响
• 由于隐私保护，对 WhatsApp 联系人列表的访问有限
• 需要正确配置 Claude 以访问你的本地 MCP 工具

安全注意事项

• 服务器与你的个人 WhatsApp 账户交互
• 消息从你的账户发出，并显示为你发送
• 仅在受信任的环境中使用

许可证

MIT

免责声明

本项目与 WhatsApp Inc. 或 Meta Platforms, Inc. 无关。请自行酌情使用，并遵守 WhatsApp 的服务条款。