内容
# WhatsApp MCP 服务器
这是一个适用于 WhatsApp 的模型上下文协议（MCP）服务器。
使用此服务器，MCP 客户端可以搜索和读取您的 WhatsApp 消息（包括图片、视频、文档和音频）、搜索联系人、向个人或群组发送消息。还可以发送媒体文件。
它通过 [whatsmeow](https://github.com/tulir/whatsmeow) 使用 WhatsApp 的网络多设备 API 连接到一个 WhatsApp 账户。消息存储在本地 SQLite 数据库中，仅在 AI 客户端调用相应的 MCP 工具时返回给它。
核心桥接器和 MCP 服务器设计适用于 macOS、Linux 和 Windows。对于两个或多个账户，请为每个账户运行一个独立的桥接器配置文件。参见 [平台设置](docs/platform-setup.md) 和 [多账户指南](docs/multi-account.md)。
## 分叉和致谢
此仓库是 [Luke Harries 的原始 `whatsapp-mcp` 项目](https://github.com/lharries/whatsapp-mcp) 的维护分叉。原始架构和实现的版权归 Luke Harries 和上游贡献者所有。原始 MIT 版权声明在 [LICENSE](LICENSE) 中保留。
### 此分叉的改进
- 支持具有独立存储、端口、身份和 MCP 注册的隔离个人和工作账户。
- 在执行消息、文件、群组更改、聊天状态更改、阻止或打字-存在操作之前添加显式确认。
- 扩展群组、账户身份、联系人解析、聊天管理、媒体、通话历史和有针对性的历史同步功能。
- 添加交付/已读回执跟踪和有界、可重放的服务器发送事件流，用于实时消息和回执。
- 改进配对，使用原生二维码处理、电话号码配对、更清晰的链接设备身份和终端回退。
- 为 macOS、Linux 和 Windows 提供持久服务指导和平台原生数据位置；macOS Contacts.app 访问仍然是可选的。
- 加强媒体处理，具有抗冲突下载、便携式文件名、正确的文档 MIME 元数据和 WhatsApp `FileName` 支持。
- 添加锁定 Python 依赖项、自动化测试、竞争/静态检查和 macOS、Linux 和 Windows 上的 CI 覆盖。
> *注意:* 与许多 MCP 服务器一样，WhatsApp MCP 受制于 [致命三重奏](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)。 因此，提示注入可能导致私人数据外流。 将桥接器绑定到 localhost，审查工具调用，并要求确认出站操作。
## 安装
### 先决条件
- Go
- Python 3.11+
- MCP 客户端，如 Codex、Claude Desktop 或 Cursor
- [uv](https://docs.astral.sh/uv/)（Python 包和环境管理器）
- FFmpeg（可选）- 仅需要将非 Opus 音频转换为可播放的 WhatsApp 语音消息。 没有 FFmpeg，仍然可以使用 `send_file` 发送原始音频。
- Whisper 转录（可选）- 通过下面描述的 `whisper` 依赖项单独安装。
### 步骤
1. **克隆此仓库**
```bash
git clone https://github.com/DJNgoma/whatsapp-mcp.git
cd whatsapp-mcp
```
2. **安装 UV 并准备 Python MCP 服务器**
UV 创建了一个隔离的 Python 环境，安装了 `uv.lock` 中记录的精确依赖项，并为您的 MCP 客户端启动了 stdio MCP 服务器。 它仅管理 Python MCP 组件；Go WhatsApp 桥接器仍然单独运行。
使用[官方说明](https://docs.astral.sh/uv/getting-started/installation/)安装 UV。 常见命令是：
```bash
# macOS with Homebrew
brew install uv
# macOS or Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```
```powershell
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
打开一个新的终端，如果安装程序更新了您的 `PATH`，然后验证 UV 并准备锁定的环境：
```bash
uv --version
cd whatsapp-mcp-server
uv sync --locked
cd ..
```
`uv sync --locked` 创建 `whatsapp-mcp-server/.venv` 并失败，而不是静默更改依赖项锁定文件。
要启用本地语音转文本，请安装可选的 [faster-whisper](https://github.com/SYSTRAN/faster-whisper) 后端：
```bash
cd whatsapp-mcp-server
uv sync --locked --extra whisper
cd ..
```
Whisper 要求和行为：
- macOS、Linux 或 64 位 Windows 上需要 Python 3.11 或更高版本。
- 首次使用时需要互联网访问以下载所选模型。 默认的多语言 `base` 模型是一个实用的 CPU 友好起点； 模型权重由 Hugging Face 客户端缓存。
- 为默认模型、依赖项、缓存和工作数据留出大约 1 GB 的空闲磁盘空间和至少 2 GB 的可用 RAM。 较大的模型需要更多的资源。
- 可以使用 CPU。 NVIDIA GPU 加速是可选的，需要安装支持的 CTranslate2 版本的 CUDA/cuDNN 组合。
- 不需要系统 FFmpeg 进行转录，因为 faster-whisper 通过 PyAV 解码音频。 FFmpeg 仍然有助于转换外发语音消息。
- 音频在本地转录。 它不会上传到外部转录 API，尽管模型权重会在首次使用时下载。
可选环境变量是 `WHATSAPP_WHISPER_MODEL`（默认为 `base`）、`WHATSAPP_WHISPER_DEVICE`（默认为 `auto`）和 `WHATSAPP_WHISPER_COMPUTE_TYPE`（默认为 `default`）。 资源上限是 `WHATSAPP_WHISPER_MAX_FILE_BYTES=26214400`、`WHATSAPP_WHISPER_MAX_DURATION_SECONDS=900`、`WHATSAPP_WHISPER_MAX_SEGMENTS=500` 和 `WHATSAPP_WHISPER_MAX_OUTPUT_CHARS=100000`。 在安装或更改这些值后重启 MCP 客户端。 在 MCP 客户端命令中使用 `run --extra whisper main.py` 而不是 `run main.py`，以便 uv 在启动服务器时始终激活可选依赖项。
3. **运行和配对 WhatsApp 桥接器**
便携式启动器选择原生每用户数据目录，打印它并在 localhost 端口 `8741` 启动桥接器：
```console
# macOS or Linux
python3 scripts/run_bridge.py --instance-id personal
# Windows PowerShell
py scripts/run_bridge.py --instance-id personal
```
存储默认位于：
- macOS: `~/Library/Application Support/whatsapp-mcp/store`
- Linux: 如果设置了 `$XDG_DATA_HOME/whatsapp-mcp/store`，否则 `~/.local/share/whatsapp-mcp/store`
- Windows: `%LOCALAPPDATA%\whatsapp-mcp\store`
在 macOS 和 Linux 上，启动器创建或加强存储目录为模式 `0700`，然后桥接器写入链接设备状态、消息或媒体。 Windows 使用当前用户的应用程序数据 ACL 而不是 POSIX 模式。 为每个并发运行的配置文件提供不同的 `--instance-id`； 桥接器从 `/api/health` 返回它，因此服务检查可以将健康进程与已经使用端口的不同帐户区分开来。
首次运行时，桥接器会将二维码写入临时 PNG 文件并自动在系统图像查看器中打开它。 当前的 WhatsApp 配对使用两次扫描：
1. 使用手机的常规相机应用扫描最新的二维码。
2. 点击 WhatsApp 出现的链接，然后在 WhatsApp 中点击 **继续**。
3. 在 WhatsApp 中再次扫描最新的二维码以确认链接。
WhatsApp 旋转配对代码，因此始终使用最新的图像。 如果系统图像查看器无法打开，则作为回退，终端中会显示二维码。
新配对使用当前主机平台作为其链接设备身份。 现有链接设备标签无法在本地更改。
或者，使用国际格式的电话号码配对：
```console
python3 scripts/run_bridge.py --instance-id personal --phone +15551234567
# Windows: py scripts/run_bridge.py --instance-id personal --phone +15551234567
```
桥接器打印一个八字符代码。 在手机上，打开 **WhatsApp > 设置 > 链接设备 > 链接设备 > 使用电话号码链接**，然后输入它。 省略 `--phone` 以使用二维码配对。
在使用 MCP 服务器时保持此进程运行。 对于后台启动，Linux systemd 和 Windows Task Scheduler 说明在 [docs/platform-setup.md](docs/platform-setup.md) 中。 在 macOS 上，您可以安装附带的 LaunchAgent：
```bash
python3 scripts/install_macos_launch_agent.py
```
安装程序从 LaunchAgent 标签中派生一个实例 ID，并且 `/api/health` 返回该确切 ID，同时连接并登录。 因此，不同端口上的不同桥接器会失败安装检查，而不是被误认为是请求的配置文件。
可选的 Contacts.app 助手仅限 macOS； WhatsApp 联系人/聊天搜索在所有支持的平台上都有效，无需它。 在 macOS 上使用 `python3 scripts/install_macos_launch_agent.py --with-contacts` 启用它。
4. **连接您的 MCP 客户端**
获取启动器选择的存储目录，以及 MCP 客户端所需的绝对路径：
```bash
python3 scripts/run_bridge.py --print-store-dir
command -v uv
cd whatsapp-mcp-server && pwd
```
在 Windows 上，使用 `py scripts/run_bridge.py --print-store-dir`、`Get-Command uv` 和 `(Resolve-Path whatsapp-mcp-server).Path` 在 PowerShell 中。
对于 **Codex** 在 macOS 或 Linux 上，使用上述返回的绝对路径注册服务器：
```bash
codex mcp add \
--env 'WHATSAPP_STORE_DIR=/absolute/path/printed/above' \
--env 'WHATSAPP_BRIDGE_URL=http://127.0.0.1:8741/api' \
whatsapp -- \
/absolute/path/to/uv \
--directory /absolute/path/to/whatsapp-mcp/whatsapp-mcp-server \
run main.py
```
验证注册：
```bash
codex mcp get whatsapp
```
在 Windows 上，使用 PowerShell 和 `Get-Command uv` 和 `Resolve-Path` 返回的路径：
```powershell
codex mcp add `
--env "WHATSAPP_STORE_DIR=C:/Users/your-name/AppData/Local/whatsapp-mcp/store" `
--env "WHATSAPP_BRIDGE_URL=http://127.0.0.1:8741/api" `
whatsapp -- `
"C:/absolute/path/to/uv.exe" `
--directory "C:/absolute/path/to/whatsapp-mcp/whatsapp-mcp-server" `
run main.py
```
在这些 Windows 命令路径中使用正斜杠，它们是有效的，并且避免反斜杠转义。
对于 **Claude Desktop** 或 **Cursor**，在以下配置中使用相同的绝对路径：
```json
{
"mcpServers": {
"whatsapp": {
"command": "/absolute/path/to/uv",
"env": {
"WHATSAPP_STORE_DIR": "/absolute/path/printed/above",
"WHATSAPP_BRIDGE_URL": "http://127.0.0.1:8741/api"
},
"args": [
"--directory",
"/absolute/path/to/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
```
在 Windows JSON 路径中使用正斜杠或转义的反斜杠（`\`）。 平台特定的 Claude Desktop 和 Cursor 配置文件位置在 [docs/platform-setup.md](docs/platform-setup.md) 中列出。
5. **重启您的 MCP 客户端并测试**
重启 Codex、Claude Desktop 或 Cursor，以便它加载新注册的服务器。 对于安全的第一项测试，请询问：
> 使用 WhatsApp 列出我最近的五个聊天记录。 不要发送任何内容。
### 平台支持
CI 配置为在 macOS、Ubuntu Linux 和 Windows 上构建和测试 Go 桥接器和 Python MCP 服务器。 此分叉的实时账户测试已在 macOS 上进行； Linux 和 Windows 仍然需要更广泛的现实世界验证，因此欢迎错误报告和兼容性反馈。 Windows 需要 CGO 和 C 编译器，因为桥接器使用 SQLite； 准确的 MSYS2 设置和持久服务说明在 [docs/platform-setup.md](docs/platform-setup.md) 中。
## 架构概述
此应用程序由两个主要组件组成：
1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): 一个 Go 应用程序，连接到 WhatsApp 的 Web API，通过二维码处理身份验证，并将消息历史存储在 SQLite 中。 它作为 WhatsApp 和 MCP 服务器之间的桥梁。
2. **Python MCP 服务器** (`whatsapp-mcp-server/`): 一个 Python 服务器，实现模型上下文协议（MCP），为兼容的 AI 客户端公开标准化的 WhatsApp 工具。
### 数据存储
- 所有消息历史记录、登录状态和下载的媒体都存储在配置的存储目录中
- 每个帐户配置文件必须有自己的存储目录、桥接器端口、服务/进程和 MCP 进程； 永远不要将两个帐户指向同一个 SQLite 存储
- 便携式启动器使用每个平台的每用户应用程序数据目录； `whatsapp-bridge/store` 仍然是直接运行的旧默认设置
- 便携式 macOS/Linux 启动器和 macOS 安装程序强制执行 `0700` 帐户状态和日志目录； 迁移的数据库和复制的私有文件被强化为 `0600`
- 数据库维护聊天和消息的表格
- 消息索引以实现高效搜索和检索
### 桥接器 API 说明
桥接器 API 故意未经身份验证，并且仅绑定到 `127.0.0.1`。 不要将其绑定到所有接口，通过反向代理公开它，通过隧道发布它，或将 MCP 确认令牌视为 HTTP 身份验证。 任何可以访问端口的本地进程都可以直接调用 API。 为每个帐户配置文件使用不同的端口、存储、进程、MCP 注册和运行状况 `instance_id`。
桥接器公开了分页的 `/api/chats` 和 `/api/messages` 端点，使用 `limit` 和 `offset`，在可以直接解析直接聊天的位置返回 `phone_number`，并通过可重放的 `GET /api/events` Server-Sent Events 流发布实时消息和回执。 SSE 客户端应使用 `Last-Event-ID` 重新连接； `event: reset` 响应表示光标落在有界重放窗口之外，客户端应通过读取端点协调。
消息读取联合直接聊天的电话 JID 和 LID 别名。 媒体字幕和通话记录被保留，本地媒体文件名包括消息 ID 以防止冲突。 有针对性的 `POST /api/history-sync` 端点请求从存储的消息锚点请求较旧或更新的历史记录； 它不能制造 WhatsApp 不返回的记录。
## 用法
连接后，Codex、Claude Desktop、Cursor 或另一个兼容的 MCP 客户端可以使用下面的工具。
### MCP 工具
连接的 MCP 客户端可以访问这些 WhatsApp 工具：
- **search_contacts**：按名称或电话号码搜索联系人
- **contacts_app_status**：检查 macOS Contacts.app 的可用性和权限
- **bridge_status**：报告实时桥接连接性和数据库读取可能已过时
- **get_own_identity**：返回连接的 WhatsApp JID、电话号码、显示名称和设备身份
- **search_contacts_chats_and_groups**：搜索直接聊天、群组、最近的聊天和可选的 macOS Contacts.app 条目
- **list_messages**：检索消息并使用可选的过滤器和上下文
- **list_chats**：列出可用的聊天并带有元数据
- **list_joined_groups**：列出实时 WhatsApp 群组和参与者计数
- **get_group_info**：读取实时群组元数据、参与者和管理员角色
- **create_group**：准备并显式确认 WhatsApp 群组的创建
- **add_participants_to_group** / **remove_participants_from_group**：准备并显式确认成员资格更改
- **promote_participants_to_admins** / **demote_participants_from_admins**：准备并显式确认管理员角色更改
- **set_chat_read_state**：准备并显式确认将聊天标记为已读或未读
- **is_on_whatsapp**：验证电话号码是否在 WhatsApp 上而无需发送
- **set_chat_mute** / **set_chat_archive**：准备并显式确认聊天状态更改
- **set_contact_block**：准备并显式确认阻止或取消阻止联系人
- **send_typing_indicator**：准备并显式确认编写、录制或暂停存在
- **get_chat**：获取特定聊天的详细信息
- **get_direct_chat_by_contact**：查找与特定联系人的直接聊天
- **get_contact_chats**：列出涉及特定联系人的所有聊天记录
- **get_last_interaction**：获取与联系人的最新消息
- **get_message_context**：检索特定消息周围的上下文
- **send_message**：准备并显式确认发送 WhatsApp 消息到电话号码或群组 JID
- **send_file**：准备并显式确认发送文件（图像、视频、原始音频、文档）
- **send_audio_message**：准备并显式确认发送音频（需要 `.ogg` Opus 文件或 FFmpeg）
- **download_media**：下载 WhatsApp 消息并获取本地文件路径
- **whisper_status**：报告可选的本地 Whisper 转录安装并显示所选模型/设备设置
- **transcribe_audio_message**：下载 WhatsApp 音频消息并在本地转录，并提供可选的语言和词汇提示
### 媒体处理
MCP 服务器支持发送和接收各种媒体类型：
#### 媒体发送
您可以向 WhatsApp 联系人发送各种媒体类型：
- **图片、视频、文档**：使用 `send_file` 工具共享任何支持的媒体类型。
- **语音消息**：使用 `send_audio_message` 工具发送音频文件作为可播放的 WhatsApp 语音消息。
- 为了最佳兼容性，音频文件应为 `.ogg` Opus 格式。
- 安装 FFmpeg * 如果 FFmpeg 已安装，系统将自动将其他音频格式（MP3、WAV 等）转换为所需格式。
- 如果没有 FFmpeg，您仍然可以使用 `send_file` 工具发送原始音频文件，但它们不会显示为可播放的语音消息。
- **文档元数据**：文档 MIME 类型和文件名得到保留，因此 PDF 等文件会带有可读的名称和正确的文件类型。
#### 媒体下载
默认情况下，数据库存储媒体元数据而不是完整的文件。使用 `download_media` 以及消息的 `message_id` 和 `chat_jid` 下载媒体。该工具返回一个平台本地路径，可以打开或传递给其他工具。
#### 可选的Whisper转录
安装 `whisper` 额外功能后，使用 `transcribe_audio_message` 以及消息工具显示的相同的 `message_id` 和 `chat_jid`。第一个请求下载配置的模型，因此可能需要更长时间。后续请求重复使用MCP进程中缓存的模型。使用 `whisper_status` 诊断安装或配置问题，而无需下载模型。
## 技术细节
1. AI客户端调用Python MCP服务器上的工具。
2. 读取工具查询本地SQLite缓存；实时操作调用Go桥。
3. Go桥与WhatsApp通信，并保持本地缓存更新。
4. 结果通过MCP服务器返回给客户端。
5. 发出和改变状态的操作在到达WhatsApp之前需要以下确认流程。
## 运行和安全边界
- 读取工具查询本地 `messages.db`。使用 `bridge_status` 确定桥是否连接；当桥停止或断开时，结果可能已过时。
- 发送和媒体下载需要实时桥。默认端点仅限本地，位于 `http://127.0.0.1:8741/api`。
- 联系人搜索可以选择性地将已知的WhatsApp直接聊天与macOS上只读的Contacts.app结果合并。启用它需要运行 `python3 scripts/install_macos_launch_agent.py --with-contacts`。没有已知聊天的联系人标记为 `has_whatsapp_chat: false`；服务器不假设每个地址簿号码都有WhatsApp。
- 联系人搜索工具需要一个非空的名称或电话号码片段；空白查询不会返回任何联系人。
- Contacts.app访问是可选的。首次使用时，macOS会询问 **WhatsApp MCP Contacts** 是否可以访问您的联系人。如果辅助程序不存在或权限被拒绝，`contacts_app_status` 会报告该状态，WhatsApp-only联系人和聊天搜索继续有效。
- 文本、文件和音频发送使用两阶段流程。第一个工具调用返回预览和一个短暂的单次令牌，而不发送。显式用户确认后需要第二个匹配调用。
- 持久性服务日志在WARN级别运行，默认省略消息正文。交互式调试可以选择加入 `--log-messages`，但这会将私有内容写入控制台或配置的日志。
- 群组、读取状态、静音、存档、阻止和输入操作使用与 outbound 消息相同的精确预览确认合约。
- 桥JSON请求正文默认为1 MiB上限（`WHATSAPP_BRIDGE_MAX_REQUEST_BODY_BYTES`），媒体下载默认为512 MiB（`WHATSAPP_BRIDGE_MAX_MEDIA_DOWNLOAD_BYTES`）。无效或非正覆盖会回退到这些默认值；在资源受限的机器上降低这些值。
- MCP消息/聊天读取上限为100，页码上限为1,000，每侧消息上下文上限为50。无效或过高的值会在数据库辅助函数中再次被限制，因此负的SQLite限制不会扩大到整个存储读取。
- 本地Whisper转录默认为25 MiB输入，15分钟解码音频，500个分段和100,000个输出字符。`whisper_status` 报告活动限制；`WHATSAPP_WHISPER_MAX_*` 环境变量可能会降低或故意提高这些限制，以便在受信任的工作站上使用。
- MCP当前无法编辑或删除消息，反应，发布状态，进行呼叫或管理产品级列表和工作流程。
## 故障排除
- 运行 `uv` 时遇到权限问题时，将其添加到 `PATH` 或使用其绝对路径。在macOS/Linux上使用 `command -v uv` 或在Windows PowerShell中使用 `Get-Command uv`。
- 使用 `bridge_status` 或 `/api/health` 端点区分停止的桥和过时的本地数据库。
- 有关macOS、Linux和Windows的服务日志和启动检查，请参阅[平台设置指南](docs/platform-setup.md)中的对应部分。
### 身份验证问题
- **二维码未显示**：重启桥启动器。在macOS上，它使用默认图像查看器；在Linux上，它使用 `xdg-open`；在Windows上，它使用注册的图像处理程序。如果图像打开失败，请使用终端中打印的二维码。
- **WhatsApp已经登录**：如果您的会话已经激活，Go桥会重新连接，而不会显示二维码。
- **达到设备限制**：WhatsApp限制了链接设备的数量。请从 **WhatsApp > 设置 > 链接设备** 中删除未使用的设备，然后重试。
- **无消息加载**：初始历史记录同步可能需要几分钟，尤其是对于有许多聊天的帐户。
- **恢复后历史记录不完整**：使用桥的目标历史记录同步端点和存储的最旧消息锚点。如果WhatsApp返回早期的记录，桥无法填充空白；检查日志并保留本地存储。
- **WhatsApp不同步**：停止桥，取消WhatsApp中受影响的链接设备，并将该配置文件的 `whatsapp.db` 移到一边，然后使用相同的存储再次配对。保留 `messages.db`；它包含本地消息历史记录。切勿使用另一个帐户的存储修复一个帐户。
有关客户端集成帮助，请参阅 [Codex MCP 文档](https://developers.openai.com/codex/mcp)、[连接本地服务器的MCP指南](https://modelcontextprotocol.io/docs/develop/connect-local-servers)（包括Claude Desktop）或 [Cursor MCP 文档](https://docs.cursor.com/context/model-context-protocol)。这些客户端说明适用于macOS、Linux和Windows的客户端；桥特定的平台命令仍在 [平台设置指南](docs/platform-setup.md) 中。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器