WhatsApp MCP

Name: WhatsApp MCP
Author: adelaidasofia

本地服务

github.com/adelaidasofia通信协作63 天前更新

代码仓库

关于 WhatsApp MCP

WhatsApp MCP 是本地服务端，让 Claude 访问 WhatsApp 聊天、联系人、搜索、在线状态及受控消息发送。它结合加密消息存储、入站消息清理、审计日志，以及发送前必须确认的步骤。

主要功能

01读取聊天、消息和联系人
02以忽略重音且容错错字的方式搜索
03使用 whisper.cpp 在本地转录语音消息
04解析 LID 别名并获取在线状态
05先起草文本、表情回应和引用回复，再确认
06加密存储数据并记录工具调用

适用场景

01搜索 WhatsApp 历史消息或联系人
02查看经过提示注入模式清理的入站聊天内容
03在本地转录语音消息
04准备消息或回应，并在发送前确认

MCP 相关

Python MCP 服务通过 stdio 向 Claude 提供 11 个工具，并调用本地 Go 桥接服务的 REST API。发送消息须先起草，再单独调用 confirm_send 确认。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "adelaidasofia-whatsapp": {
      "command": "uvx",
      "args": [
        "adelaidasofia-whatsapp-mcp"
      ],
      "env": {
        "WHATSAPP_BRIDGE_HOST": "<WHATSAPP_BRIDGE_HOST>",
        "WHATSAPP_BRIDGE_PORT": "<WHATSAPP_BRIDGE_PORT>",
        "WHATSAPP_VAULT_CRM_PATH": "<WHATSAPP_VAULT_CRM_PATH>",
        "WHATSAPP_WHISPER_BACKEND": "<WHATSAPP_WHISPER_BACKEND>",
        "WHATSAPP_WHISPER_API_KEY": "<WHATSAPP_WHISPER_API_KEY>",
        "WHATSAPP_WHISPER_MODEL": "<WHATSAPP_WHISPER_MODEL>",
        "WHATSAPP_SCRUB_PROMPT_INJECTION": "<WHATSAPP_SCRUB_PROMPT_INJECTION>",
        "WHATSAPP_AUDIT_LOG": "<WHATSAPP_AUDIT_LOG>",
        "WHATSAPP_ENCRYPT_DB": "<WHATSAPP_ENCRYPT_DB>"
      }
    }
  }
}

启动命令uvx adelaidasofia-whatsapp-mcp

需要配置的环境变量

WHATSAPP_BRIDGE_HOSTHostname for the Go bridge REST API.

WHATSAPP_BRIDGE_PORTPort for the Go bridge REST API.

WHATSAPP_VAULT_CRM_PATHAbsolute path to a vault CRM folder for auto-injection (e.g., Obsidian 'CRM/'). When unset, CRM injection is disabled.

WHATSAPP_WHISPER_BACKENDVoice-note transcription backend. 'local-cpp' (default, private) or 'openai-api' (opt-in).

WHATSAPP_WHISPER_API_KEY密钥OpenAI API key. Required only when WHATSAPP_WHISPER_BACKEND=openai-api.

WHATSAPP_WHISPER_MODELwhisper.cpp model name. Only used when backend is local-cpp.

WHATSAPP_SCRUB_PROMPT_INJECTIONStrip known prompt-injection patterns from incoming messages before the LLM sees them.

WHATSAPP_AUDIT_LOGLog every tool call to audit.log.

WHATSAPP_ENCRYPT_DBEnable SQLCipher DB encryption with the key sourced from macOS Keychain.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiadelaidasofia-whatsapp-mcp0.1.1stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

whatsapp-mcp

一款面向 Claude 的 WhatsApp MCP 服务，直接基于 whatsmeow 构建。数据静态加密，可清除提示词注入内容；每次发送都必须先起草并确认；提供完整审计跟踪，并设有每日 CI 安全检查。持续维护中。

为什么选择它？

星标最多的 WhatsApp MCP（lharries/whatsapp-mcp，5.6K 星标）是这种模式的架构参考，但自 2025 年 7 月以来就没有发布新版本，并将致命三要素问题完全留给用户处理。此实现弥补了这些不足：

	典型实现	此实现
最近发布	2025 年 7 月	持续更新
数据库加密	未加密的 SQLite	使用 SQLCipher，密钥存储在平台的密钥库中（macOS Keychain / Windows Credential Manager / libsecret）
提示词注入清理器	无	清理每条收到的消息
发送安全性	立即发送	必须在起草和发送之间调用 `confirm_send`
审计日志	无	记录每次工具调用，保留 30 天
语音消息	不转录	使用本地 `whisper.cpp`，默认针对西班牙语调优
LID 别名解析	上游存在一系列未解决的问题	已实现，并提供针对旧版对话的回填迁移
CI 安全	无	`govulncheck` + `pip-audit` + Dependabot，每日运行

这不是一个分支。Go 桥接层直接基于 whatsmeow 构建；Python MCP 层和 SQLite 架构均为原创。仅将其他实现（lharries、LukasHaas、verygoodplugins）作为参考。

它能提供什么

Claude 可以：

读取你的 WhatsApp 聊天、消息和联系人
搜索消息，支持忽略重音符号并容忍拼写错误
通过本地 whisper.cpp 转录语音消息（默认针对西班牙语调优）
解析 LID（Linked IDentifier，链接标识符）名称，而不是显示数字占位符
发送文本消息、表情回应和引用回复；起草与发送之间必须经过 confirm_send 步骤
读取聊天时，从你的 Obsidian 知识库中提取匹配的 CRM 上下文
只查看经过提示词注入清理的消息文本，绝不会看到原始的对抗性输入

所有内容都在你的本机运行。不进行云端同步，不收集遥测数据。可选的 OpenAI Whisper 后端默认关闭，需主动启用。

架构

两个组件，均在本地运行：

whatsapp-bridge/（Go）。仅绑定到 127.0.0.1。封装 whatsmeow，用于 WhatsApp Web 多设备协议。使用 SQLCipher 加密的 SQLite 进行持久化。处理 QR 码和配对码身份验证（可实时刷新的终端 QR 码，支持 Windows 安全渲染；另提供无界面身份验证 API — GET /api/auth/qr、POST /api/auth/pair-phone、POST /api/auth/reconnect — 让 GUI 或监控程序无需终端即可驱动配对）、媒体上传/下载、从 StreamReplaced 冲突中恢复会话，以及通话历史记录。提供 Python MCP 层使用的 REST API。
whatsapp-mcp-server/（Python，FastMCP）。使用 Go bridge REST API。向 Claude 提供 11 个 MCP 工具：完整的读取功能（聊天、消息、联系人）、不区分重音符号的搜索、在线状态（正在输入、在线、标记为已读），以及文本发送 + 表情回应 + 引用回复，并强制要求 confirm_send。通过 uv 和 stdio 传输运行。

安装

打开 Claude Code，粘贴：

/plugin marketplace add adelaidasofia/whatsapp-mcp
/plugin install whatsapp-mcp@whatsapp-mcp

这会安装 Python MCP 服务端。Go bridge 仍需要通过手机完成一次性 QR 配对流程 — 具体步骤请参阅下方的旧版安装说明。

手动安装（完整 Go bridge + QR 配对）

按操作系统查看 SETUP.md 获取分步安装说明。简要步骤如下：

从 Releases 获取预构建的 bridge 二进制文件（Windows/macOS/Linux — 无需编译器），或从源代码构建（需要 Go 1.26+ 和 C 工具链）
安装 Python 3.11+ 和 uv，用于 MCP 服务层
克隆此仓库；运行 scripts/check_prerequisites.sh 验证（Windows：scripts\check_prerequisites.ps1）
启动 bridge：./bin/whatsapp-bridge（Windows：.\bin\whatsapp-bridge.exe）
扫描 QR 码（二维码会在原位置刷新 — 请始终扫描屏幕上显示的二维码），或使用 --pair-phone +15551234567 输入代码进行配对
在 Claude Code 的 .mcp.json 中注册 MCP
重启 Claude Code

只有启用语音留言转录功能时才需要 FFmpeg 和 whisper.cpp（默认关闭）。

配置

所有配置均可通过环境变量设置。完整列表请参阅 .env.example。

关键变量：

变量	默认值	用途
`WHATSAPP_BRIDGE_PORT`	`8080`	Go bridge REST API 端口
`WHATSAPP_DB_PATH`	`$HOME/.claude/whatsapp-mcp/store/messages.db`	加密的 SQLite 数据库
`WHATSAPP_MEDIA_PATH`	`$HOME/.claude/whatsapp-mcp/media/`	媒体文件存储路径
`WHATSAPP_VAULT_CRM_PATH`	空	用于自动注入的 vault CRM 文件夹绝对路径（例如，Obsidian `👤 CRM/`）。未设置时，将禁用 CRM 注入。
`WHATSAPP_WHISPER_BACKEND`	`off`	`off`（零配置启动）、`local-cpp`（隐私模式，需要 whisper 模型）或 `openai-api`（选择启用）
`WHATSAPP_WHISPER_API_KEY`	空	仅当后端为 `openai-api` 时必需
`WHATSAPP_WHISPER_MODEL`	`large-v3`	whisper.cpp 模型名称
`WHATSAPP_SCRUB_PROMPT_INJECTION`	`true`	在 Claude 查看收到的消息前，移除已知的提示词注入模式
`WHATSAPP_AUDIT_LOG`	`true`	将每次工具调用记录到 `audit.log`
`WHATSAPP_ENCRYPT_DB`	`true`	启用 SQLCipher 数据库加密；密钥存储在平台机密存储中（macOS Keychain / Windows Credential Manager / libsecret）
`WHATSAPP_DB_KEY`	空	显式指定的 64 位十六进制 SQLCipher 密钥覆盖值（跳过平台存储）。用于无界面环境/CI/自定义机密管理器的备用选项，以及无法读取机密存储时的恢复途径 — 详见下文

数据库密钥与 `WHATSAPP_DB_KEY`

启用 WHATSAPP_ENCRYPT_DB=true（默认值）时，桥接程序会使用存储在平台密钥库中的 256 位 SQLCipher 密钥加密消息存储。密钥生命周期的处理有意采取保守策略，因为错误的密钥会悄无声息地使所有已存储消息无法访问：

仅当密钥库明确返回“没有此项”（macOS errSecItemNotFound、Windows ERROR_NOT_FOUND、libsecret 明确未找到）且尚不存在非空的存储数据库时，才会生成新密钥。
其他任何读取失败情况——密钥链已锁定、没有 D-Bus 会话、访问权限已撤销——都会导致桥接程序报错退出，而不是生成新密钥：原密钥可能仍然存在，覆盖它会导致加密存储永久无法解密。错误信息会指出解决方法（例如 security unlock-keychain）。
如果密钥库中没有密钥，但已存在包含数据的存储数据库，桥接程序也会拒绝生成新密钥，并要求你提供原始密钥。

WHATSAPP_DB_KEY（64 个十六进制字符 = 32 字节，例如 openssl rand -hex 32）可用于处理上述所有情况：设置后会直接使用该密钥，且不会访问平台密钥库。可在无头/CI 机器、自定义密钥管理器、在新机器上恢复存储，或平台密钥库不可用时启动程序时使用。

安全性

此 MCP 是 Claude 技术栈中信任级别最高的组件，因为你收到的每条 WhatsApp 消息都会经过它。有关威胁模型、工具风险等级分类以及完整的加固措施列表，请参阅 SECURITY.md。

简而言之：

桥接程序仅绑定到 127.0.0.1，绝不绑定到 0.0.0.0
SQLite 使用 SQLCipher 进行静态加密；密钥存储在平台密钥库中（macOS Keychain / Windows Credential Manager / libsecret），并提供明确的 WHATSAPP_DB_KEY 备用方式
每次工具调用都会记录到 audit.log，保留 30 天
发送工具要求在起草和发送之间执行明确的 confirm_send 步骤
收到的消息文本在 Claude 看到之前会经过提示词注入清理器处理
whatsmeow 固定到特定提交；升级前必须审查差异
默认不进行遥测，也不调用外部 API

状态

v0.1.0，积极维护中。

已交付：实时刷新的 QR 码（轮换时原位重绘、兼容 Windows 的渲染、过期后自动生成新批次）+ 配对码身份验证（输入 8 位代码，支持 Android + iOS）+ 面向监督程序的无头身份验证 API、完整读取功能（聊天、消息、联系人）、不区分重音符号的 NFD 规范化搜索、LID 别名解析及旧版会话的回填迁移、Baileys 存储导入以一次性迁移历史记录、保险库格式的 Markdown 导出、本地 whisper.cpp 语音转录、状态功能（正在输入、在线、标记为已读）、带强制 confirm_send 的文本发送、表情回应、引用回复、提示词注入清理器、使用 macOS Keychain 密钥处理的 SQLCipher 加密持久化、审计日志、CI 安全门禁。

尚未交付：媒体发送（图片、文档）、音频消息发送（FFmpeg-Opus 路径）、群组广播辅助工具。

完整历史记录请参阅 CHANGELOG.md。

MCP Registry

已在官方 MCP Registry 发布，名称为 io.github.adelaidasofia/whatsapp-mcp。提供两个可用渠道：

.mcpb bundle（标准渠道，推荐）——可在 Claude Desktop / Cursor / 任何支持 MCPB 的客户端中一键安装。作为 GitHub release 资源发布于 releases/latest/download/whatsapp-mcp.mcpb。release 清单中包含 SHA256，用于检测篡改。
PyPI 软件包（adelaidasofia-whatsapp-mcp）——历史渠道；可通过 uvx adelaidasofia-whatsapp-mcp 用于 stdio 安装流程。未加前缀的名称（whatsapp-mcp、whatsapp-mcp-server）已被 PyPI 上无关的项目占用，因此使用以用户名为前缀的命名空间。

验证标记 mcp-name: io.github.adelaidasofia/whatsapp-mcp 已嵌入此 README（顶部附近的 HTML 注释中），以便 Registry 在发布时验证软件包与服务的归属关系。

**发布流水线：**通过 Mycelium MCP 发布流水线构建并发布（分两阶段：构建 .mcpb bundle，然后执行 gh release + mcp-publisher publish）。同一流水线还产出了此系列中的全部 16 个相关 MCP。

遥测

此插件在某台设备上的 Claude Code 会话中首次加载时，会向 myceliumai.co 发送一条匿名安装信号。

发送内容：

插件名称（例如 slack-mcp）
插件版本（例如 0.1.0）

不会发送：

不会发送用户标识符、姓名、电子邮件、令牌或 API 密钥
不会发送文件路径、消息内容或任何工作相关内容
去重处理后不会存储 IP 地址

**原因：**帮助维护者了解用户实际安装了哪些插件，从而将精力投入到有人使用的插件上。

**退出方式：**启动 Claude Code 前设置环境变量 MYCELIUM_NO_PING=1。此 hook 会完全跳过网络请求。已发送过信号的安装会在 ~/.mycelium/onboarded-<plugin> 留下标记文件；如果想重置状态，请将其删除。

许可证

MIT。请参阅 LICENSE。

与 WhatsApp 或 Meta 无关

WhatsApp 是 Meta Platforms, Inc. 的商标。本项目是一个独立的开源工具，使用 WhatsApp 的公开多设备协议。使用此工具可能违反 WhatsApp 的服务条款。使用风险由您自行承担。作者不提供任何保证，也不对账号停用、数据丢失或其他后果承担责任。

由 Mycelium AI 构建。MIT 许可证。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

WhatsApp MCP

关于 WhatsApp MCP

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

whatsapp-mcp

为什么选择它？

它能提供什么

架构

安装

配置

数据库密钥与 WHATSAPP_DB_KEY

安全性

状态

MCP Registry

相关 MCP

遥测

许可证

与 WhatsApp 或 Meta 无关

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

数据库密钥与 `WHATSAPP_DB_KEY`