Whatsapp

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 或更高版本
• 互联网连接

安装

# 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"]
      }
    }
  ]
}

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 执行错误
• 处理进程级异常

在 Claude 中使用 WhatsApp MCP 工具

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

发送消息

示例提示词：

• “给 John 发一条 WhatsApp 消息，告诉他我开会要迟到 10 分钟”
• “在 WhatsApp 上给 Sarah 发以下消息：这是你要的文档”
• “在 WhatsApp 上给妈妈发‘生日快乐！’”

查看 WhatsApp 状态

示例提示词：

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

获取联系人信息

示例提示词：

• “可以列出我最近联系过的 WhatsApp 联系人吗？”
• “告诉我最近在 WhatsApp 上给谁发过消息”

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

限制

• 由于依赖 AppleScript，仅适用于 macOS
• 需要安装 WhatsApp 桌面应用
• WhatsApp UI 的变化可能会影响联系人选择
• 由于隐私保护措施，可访问的 WhatsApp 联系人列表有限
• 需要正确配置 Claude，才能访问本地 MCP 工具

安全注意事项

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

许可证

MIT

免责声明

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