Whatsapp MCP 2 0

WhatsApp MCP 2.0

通过以下方式连接到WhatsApp的模型上下文协议（MCP）服务器 百利甜酒，为人工智能提供管理WhatsApp的能力。

Architecture Diagram

特性

• 列出和搜索聊天记录、联系人和消息
• 发送短信和文件（图像、视频、文档、音频）
• 从收到的消息中下载媒体
• 通过兼容Whisper的API（Groq，OpenAI）转录语音笔记
• 回复带有阿联酋DNCR违规警告的垃圾邮件
• 在所有聊天或特定聊天中搜索全文消息
• 首次配对时自动历史同步（二维码扫描）
• 多实例安全：只有一个进程连接到WhatsApp；extra从SQLite以只读方式运行
• 通过VCF文件从电话通讯簿导入联系人姓名

先决条件

• Node.js 18+
• 具有活动电话号码的WhatsApp帐户

设置

# Install dependencies
npm install

# Build
npm run build

# Start the server
npm start

第一次运行时，二维码会打印到stderr。用手机上的WhatsApp扫描：

WhatsApp>设置>链接设备>链接设备

扫描后，服务器会同步您的聊天记录，并开始监听新消息。身份验证凭据保存到 auth_info/ 因此后续开始会自动重新连接。

MCP客户端配置

将服务器添加到MCP客户端配置中（例如Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/whatsapp-mcp/dist/index.js"],
      "env": {
        "WHISPER_API_URL": "https://api.groq.com/openai/v1/audio/transcriptions",
        "WHISPER_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

这 env 块是可选的，只需要用于语音笔记转录（见下文）。

语音笔记转录

这 transcribe_voice_note 该工具使用Whisper兼容的语音转文本API来转录语音笔记。音频从WhatsApp下载到内存中，发送到API，然后丢弃-任何东西都不会保存到磁盘。转录被缓存在数据库中，因此重复调用是即时的。

配置

在MCP客户端配置中设置这些环境变量 env 块：

Groq（推荐-免费等级）

"env": {
  "WHISPER_API_URL": "https://api.groq.com/openai/v1/audio/transcriptions",
  "WHISPER_API_KEY": "gsk_..."
}

在获取免费API密钥 console.groq.com.

开放人工智能

"env": {
  "WHISPER_API_URL": "https://api.openai.com/v1/audio/transcriptions",
  "WHISPER_API_KEY": "sk-...",
  "WHISPER_MODEL": "whisper-1"
}

可用工具

确认流程

这 send_message, reply_spam, delete_message，以及 delete_chat 工具使用两步确认流程来防止意外操作。调用时，它们首先返回一个预览，显示：

• 收件人姓名 （来自您的联系人数据库）
• 电话号码
• 消息内容 （用于发送）或 消息id （用于删除）

只有在您确认后才会执行该操作。人工智能助手必须再次调用该工具 confirmed: true 继续。

导入电话联系人

WhatsApp不会将您手机的地址簿名称同步到链接/配套设备。要查看联系人姓名而不是电话号码，请从VCF（vCard）文件导入：

从手机导出联系人

苹果手机： iCloud.com>通讯录>全选>导出vCard

安卓： 通讯录应用程序>设置>导出>导出到.vcf文件

导入数据库

# Place the VCF file in the contacts/ directory (git-ignored)
mkdir -p contacts
cp ~/Downloads/contacts.vcf contacts/

# Preview matches without making changes
npm run import-contacts -- contacts/contacts.vcf --dry-run

# Run the import
npm run import-contacts -- contacts/contacts.vcf

导入程序使用以下方法将您地址簿中的电话号码与数据库中现有的WhatsApp JID进行匹配：

1. 精确匹配 --标准化电话号码直接匹配已知的JID
2. 模糊匹配 --最后9位数字匹配，捕捉本地与国际格式差异（例如。 05xxxxxxxx 对比 9715xxxxxxxx)

模糊匹配单独列出，以便您进行验证。与一起跑步 --dry-run 第一。

项目结构

src/
  index.ts          Entry point, lock file, MCP server setup
  whatsapp.ts       Baileys client, event handling, high-level API
  db.ts             SQLite database layer (better-sqlite3)
  tools.ts          MCP tool definitions
  transcribe.ts     Whisper API client for voice note transcription
  utils.ts          Shared helpers (JID conversion, MIME types)
  import-contacts.ts  VCF contact import script

auth_info/          WhatsApp authentication credentials (git-ignored)
store/              SQLite database (git-ignored)
downloads/          Downloaded media files (git-ignored)
contacts/           Imported contact files (git-ignored)
patches/            Baileys patches applied via patch-package

事件处理

Baileys在历史同步期间缓冲事件，并将其作为合并地图刷新。服务器使用 sock.ev.process() （非个人 .on() 监听器）正确接收缓冲和实时事件。

多实例安全

文件锁(store/.whatsapp.lock)确保一次只有一个进程连接到WhatsApp。其他实例（例如，来自Claude Desktop的生成多个MCP服务器的实例）以只读模式运行，在不打开第二个WebSocket连接的情况下提供SQLite的数据。

历史同步

在首次配对（二维码扫描）时，WhatsApp会在多个同步事件中提供您的聊天历史记录。服务器将所有聊天记录、联系人和消息保存到SQLite。历史同步仅在第一次配对时发生——重新连接会重用现有数据库。

故障排除

二维码未出现： 确保您直接运行服务器（而不是通过MCP客户端），这样您就可以看到stderr输出。使用 npm run dev 为了发展。

初始同步后状态515断开连接： 这很正常。WhatsApp发送 restartRequired 初始数据转储后的信号。服务器会自动以指数回退方式重新连接。

手机上“无法完成同步”： 在第一次配对时短暂出现的装饰性消息。连接稳定后，它会自行清除。

状态401（已注销）： 您的会话已无效。删除 auth_info/ 并重新扫描二维码。

显示电话号码而不是姓名的聊天： WhatsApp不会将通讯簿名称同步到链接的设备。使用上述VCF联系人导入功能。

发展

# Run with hot-reload
npm run dev

# Type-check without emitting
npx tsc --noEmit

# Build for production
npm run build

免责声明

本软件按原样提供，不提供任何形式的保修。作者对如何使用此代码不承担任何责任。使用风险由您自行承担，并遵守WhatsApp的服务条款和所有适用法律。

许可证

麻省理工学院