金大哥 - WhatsApp Desktop MCP 详情

article

README

🚀 WhatsApp MCP 服务器

WhatsApp MCP（模型上下文协议）服务器是一个基于 Node.js 的应用程序，它能让你通过 AppleScript 自动化，在 macOS 上与已安装的 WhatsApp 桌面应用程序进行编程交互。无需手动操作 WhatsApp 用户界面，就能实现发送消息和检查 WhatsApp 状态等功能。

🚀 快速开始

若要使用 WhatsApp MCP 服务器，你需要满足以下要求：

Windows、macOS 或 Linux 系统
Node.js 14.17.0 或更高版本
npm 6.0.0 或更高版本
安装并登录到 WhatsApp 桌面应用程序

安装步骤如下：

下载源代码包
解压文件包
打开终端，导航到解压目录
运行命令：npm install
成功安装后，在终端运行 npm start 开始服务

✨ 主要特性

1. 发送联系人消息

可以向 WhatsApp 联系人列表中的特定联系人发送文本消息，具体特点如下：

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

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

验证 WhatsApp 应用程序是否当前运行，具备以下功能：

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

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

由于 WhatsApp 的隐私保护限制，此功能提供有限的可用性：

提醒用户有关 WhatsApp 的隐私限制
要求用户提供确切的联系人名称以进行消息传输

📦 安装指南

下载源代码包
解压文件包
打开终端，导航到解压目录
运行命令：npm install
成功安装后，在终端运行 npm start 开始服务

💻 使用示例

基础用法

发送消息

curl -X POST http://localhost:3000/api/send-message \
     -H "Content-Type: application/json" \
     -d '{"to": "+1234567890", "message": "你好！"}'

检查状态

curl http://localhost:3000/api/status

📚 详细文档

参考项目根目录下的 docs 文件夹中的 API 文档
通过配置文件自定义服务器参数
使用 RESTful API 或 CLI 调用功能

集成指南

安装并运行 WhatsApp MCP 服务器
配置 Claude Desktop 的 MCP 工具设置

添加以下内容到 app-settings.json：

"mcp.tools.whatsapp": {
  "host": "localhost",
  "port": 3000,
  "timeout": 5000
}

在 Claude Desktop 中启用 MCP 工具插件

🔧 技术细节

使用工具

@modelcontextprotocol/sdk - MCP 服务器和 stdio 运输
Zod - 模式验证
Node.js 内置模块（child_process、util、fs）
AppleScript 实现 macOS 自动化

架构

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

实现细节

使用 Node.js 开发，支持异步非阻塞编程模型
基于事件驱动架构实现高效通信
通过模块化设计提高代码复用性
遵循标准软件开发规范和命名惯例

工具细节

whatsapp-send-message：通过 WhatsApp 桌面应用程序发送消息
whatsapp-get-status：获取 WhatsApp 的当前运行状态
whatsapp-list-contacts：列出最近使用的 WhatsApp 联系人列表

📄 许可证

本项目采用 MIT 许可证。

⚠️ 重要提示

此项目未获得 WhatsApp Inc. 或 Meta Platforms, Inc. 的官方支持。使用前请仔细阅读 WhatsApp 的服务条款，并自行承担风险。

💡 使用建议

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

由于该项目依赖 AppleScript，目前仅限 macOS 系统使用。

受限于 WhatsApp UI 更新对联系人选择的影响以及隐私保护，可能无法访问完整的联系人列表。

若要使用相关功能，需先配置 Claude Desktop。

WhatsApp Desktop