开源：WhatsApp MCP 服务器集成

这是一个用于 WhatsApp 的 Model Context Protocol（MCP）服务器。

借助它，你可以搜索和读取个人 WhatsApp 消息（包括图片、视频、文档和语音消息），搜索联系人，并向个人或群组发送消息。你还可以发送图片、视频、文档和语音消息等媒体文件。

它通过 WhatsApp Web 多设备 API（使用 whatsmeow library）直接连接到你的个人 WhatsApp 账户。所有消息都存储在本地 SQLite 数据库中，只有当 Agent 通过你所控制的工具访问这些消息时，消息才会被发送给 LLM（例如 Claude）。

下面展示了它连接到 Claude 后可以完成的操作示例。

如果想获取这个项目以及我参与的其他项目的最新动态，请在此处输入你的电子邮箱。

注意：与许多 MCP 服务器一样，WhatsApp MCP 也面临“致命三要素”（lethal trifecta）风险。这意味着 prompt injection 可能导致私人数据泄露。

• Anthropic Claude Desktop app（或 Cursor）
• UV（Python package manager），使用 curl -LsSf https://astral.sh/uv/install.sh | sh 安装
• FFmpeg（可选）——仅处理语音消息时需要。如果想把音频文件作为可播放的 WhatsApp 语音消息发送，文件必须采用 .ogg Opus 格式。安装 FFmpeg 后，MCP 服务器会自动转换非 Opus 音频文件。即使没有 FFmpeg，你仍然可以使用 send_file 工具发送原始音频文件。

克隆此仓库：git clone https://github.com/lharries/whatsapp-mcp.git cd whatsapp-mcp

克隆此仓库

git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp

运行 WhatsApp bridge：进入 whatsapp-bridge 目录，然后运行 Go application：cd whatsapp-bridge go run main.go。第一次运行时，系统会提示你扫描 QR code。使用手机上的 WhatsApp app 扫描 QR code 以完成身份验证。大约 20 天后，你可能需要重新进行身份验证。

运行 WhatsApp bridge

进入 whatsapp-bridge 目录，然后运行 Go application：

cd whatsapp-bridge
go run main.go

第一次运行时，系统会提示你扫描 QR code。使用手机上的 WhatsApp app 扫描 QR code 以完成身份验证。

大约 20 天后，你可能需要重新进行身份验证。

连接 MCP server：复制下面的 JSON，并填写正确的 {{PATH}} 值：{ "mcpServers": { "whatsapp": { "command": "{{PATH_TO_UV}}", // Run which uvand place the output here "args": [ "--directory", "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, runpwd and enter the output here + "/whatsapp-mcp-server" "run", "main.py" ] } } }。对于 Claude，请将其保存为 Claude Desktop 配置目录中的 claude_desktop_config.json：~/Library/Application Support/Claude/claude_desktop_config.json。对于 Cursor，请将其保存为 Cursor 配置目录中的 mcp.json：~/.cursor/mcp.json。

连接 MCP server

复制下面的 JSON，并填写正确的 {{PATH}} 值：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

对于 Claude，请将其保存为 Claude Desktop 配置目录中的 claude_desktop_config.json：

~/Library/Application Support/Claude/claude_desktop_config.json

对于 Cursor，请将其保存为 Cursor 配置目录中的 mcp.json：

~/.cursor/mcp.json

重启 Claude Desktop / Cursor：打开 Claude Desktop，现在应该可以看到 WhatsApp 已成为可用的 integration。或者重启 Cursor。

重启 Claude Desktop / Cursor

打开 Claude Desktop，现在应该可以看到 WhatsApp 已成为可用的 integration。

Windows 兼容性

如果你在 Windows 上运行此项目，请注意，go-sqlite3 需要启用 CGO 才能正常编译和运行。Windows 默认禁用 CGO，因此你需要明确启用它，并安装一个 C compiler。

安装 C compiler

我们建议使用 MSYS2 在 Windows 上安装 C compiler。安装 MSYS2 后，请确保把 ucrt64\bin 文件夹添加到 PATH。→ 此处提供了分步指南。

安装 C compiler

我们建议使用 MSYS2 在 Windows 上安装 C compiler。安装 MSYS2 后，请确保把 ucrt64\bin 文件夹添加到 PATH。→ 此处提供了分步指南。

启用 CGO 并运行 app：cd whatsapp-bridge go env -w CGO_ENABLED=1 go run main.go

启用 CGO 并运行 app

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

如果没有完成这些设置，你很可能会遇到以下错误：

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

架构概览

此应用由两个主要组件构成：

• Go WhatsApp Bridge（whatsapp-bridge/）：一个连接 WhatsApp Web API 的 Go application，通过 QR code 处理身份验证，并将消息历史记录存储到 SQLite 中。它充当 WhatsApp 与 MCP server 之间的桥梁。

• Go WhatsApp Bridge（whatsapp-bridge/）：一个连接 WhatsApp Web API 的 Go application，通过 QR code 处理身份验证，并将消息历史记录存储到 SQLite 中。它充当 WhatsApp 与 MCP server 之间的桥梁。

• Python MCP Server（whatsapp-mcp-server/）：一个实现 Model Context Protocol（MCP）的 Python server，为 Claude 提供标准化工具，使其能够与 WhatsApp 数据交互并收发消息。

• Python MCP Server（whatsapp-mcp-server/）：一个实现 Model Context Protocol（MCP）的 Python server，为 Claude 提供标准化工具，使其能够与 WhatsApp 数据交互并收发消息。

所有消息历史记录都存储在 whatsapp-bridge/store/ 目录内的 SQLite 数据库中。

数据库维护聊天和消息的数据表。

消息会被建立索引，以便高效地搜索和检索。

连接完成后，你可以通过 Claude 与 WhatsApp 联系人互动，在 WhatsApp 对话中利用 Claude 的 AI 能力。

Claude 可以使用以下工具与 WhatsApp 交互：

• search_contacts：按姓名或电话号码搜索联系人
• list_messages：检索消息，支持可选的筛选条件和上下文
• list_chats：列出可用聊天及其 metadata
• get_chat：获取特定聊天的信息
• get_direct_chat_by_contact：查找与特定联系人的一对一聊天
• get_contact_chats：列出涉及特定联系人的所有聊天
• get_last_interaction：获取与某位联系人之间的最新消息
• get_message_context：检索特定消息前后的上下文
• send_message：向指定电话号码或 group JID 发送 WhatsApp 消息
• send_file：向指定接收方发送文件（图片、视频、原始音频或文档）
• send_audio_message：将音频文件作为 WhatsApp 语音消息发送（文件必须是 .ogg opus 文件，或者必须安装 ffmpeg）
• download_media：下载 WhatsApp 消息中的媒体，并获取其本地文件路径

媒体处理功能

MCP server 支持发送和接收多种媒体类型：

你可以向 WhatsApp 联系人发送多种媒体：

• 图片、视频和文档：使用 send_file 工具分享任何受支持的媒体类型。

• 语音消息：使用 send_audio_message 工具将音频文件作为可播放的 WhatsApp 语音消息发送。为获得最佳兼容性，音频文件应采用 .ogg Opus 格式。安装 FFmpeg 后，系统会自动把其他音频格式（MP3、WAV 等）转换成所需格式。如果没有 FFmpeg，你仍然可以使用 send_file 工具发送原始音频文件，但它们不会显示为可播放的语音消息。

为获得最佳兼容性，音频文件应采用 .ogg Opus 格式。

安装 FFmpeg 后，系统会自动把其他音频格式（MP3、WAV 等）转换成所需格式。

如果没有 FFmpeg，你仍然可以使用 send_file 工具发送原始音频文件，但它们不会显示为可播放的语音消息。

默认情况下，本地数据库只存储媒体的 metadata。消息会表明已发送媒体。要访问这些媒体，你需要使用 download_media 工具，并传入 message_id 和 chat_jid（打印包含媒体的消息时会显示这些信息）。该工具会下载媒体并返回文件路径，随后可以打开该文件，或将它传给另一个工具。

Claude 向 Python MCP server 发送请求。

MCP server 通过 Go bridge 查询 WhatsApp 数据，或直接查询 SQLite 数据库。

Go 组件访问 WhatsApp API，并让 SQLite 数据库保持最新状态。

数据沿着这条链路返回 Claude。

发送消息时，请求从 Claude 经由 MCP server 传递到 Go bridge，最终到达 WhatsApp。

如果运行 uv 时遇到权限问题，可能需要将它添加到 PATH，或者使用该可执行文件的完整路径。

请确保 Go application 和 Python server 都在运行，否则 integration 无法正常工作。

身份验证问题

• QR Code 未显示：如果 QR code 没有出现，请尝试重启身份验证脚本。如果问题仍然存在，请检查你的终端是否支持显示 QR code。

• WhatsApp 已登录：如果 session 已处于活跃状态，Go bridge 会自动重新连接，不会显示 QR code。

• 已达到设备上限：WhatsApp 会限制 linked devices 的数量。如果达到上限，你需要在手机 WhatsApp 中移除一台现有设备（Settings > Linked Devices）。

• 没有加载消息：首次完成身份验证后，消息历史记录可能需要几分钟才能加载完毕；如果你的聊天很多，所需时间会更长。

• WhatsApp 不同步：如果 WhatsApp 消息与 bridge 不再同步，请删除两个数据库文件（whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db），然后重启 bridge 并重新进行身份验证。

如需排查其他 Claude Desktop integration 问题，请参阅 MCP documentation。其中包含查看日志和解决常见问题的实用建议。