WhatsApp MCP 服务器

概述

WhatsApp MCP（模型上下文协议）服务器是一个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

架构

• 使用模型上下文协议（MCP）进行标准化工具通信
• 使用stdio传输进行通信
• 执行AppleScript命令以与WhatsApp桌面应用程序交互
• 实现全面的错误日志记录用于调试

要求

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

安装

# 克隆仓库
git clone https://github.com/yourusername/whatsapp-mcp-server.git

# 导航到项目目录
cd whatsapp-mcp-server

# 安装依赖
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"]
      }
    }
  ]
}

3. 测试集成
   • 创建一个与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执行错误
• 进程级异常处理

使用WhatsApp MCP工具与Claude

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

发送消息

示例提示：

• “给John发一条WhatsApp消息说我会晚10分钟到达我们的会议”
• “在WhatsApp上给Sarah发送以下文本：这是你请求的文档”
• “在WhatsApp上给妈妈发送‘生日快乐！’”

检查WhatsApp状态

示例提示：

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

获取联系人信息

示例提示：

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

Claude将根据您的请求使用适当的MCP工具，并提供结果反馈。

限制

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

安全注意事项

• 该服务器与您的个人WhatsApp帐户互动
• 消息从您的帐户发送，并显示为由您发送
• 仅在受信任的环境中使用

许可证

MIT

免责声明

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