WhatsApp MCP

WhatsApp MCP服务器是一个连接WhatsApp与AI助手（如Claude或Cursor）的工具，允许用户搜索和读取消息、联系人列表，并发送新消息或文件。它通过WhatsApp网页多设备API实现与个人账户的连接，支持消息处理、多媒体传输和数据库同步，适用于客服支持、个人事务管理或团队协作。

核心功能

WhatsApp MCP服务器提供了多种核心功能，帮助用户高效管理WhatsApp聊天记录和消息交互。

• 联系人搜索：根据姓名或电话号码快速查找联系人。
• 历史消息检索：按条件筛选并查看过去的聊天记录。
• 媒体文件传输：支持发送图像、视频、文档或音频文件。
• 语音消息发送：将音频文件转换为WhatsApp支持的格式并发送。
• 数据库同步：实时更新本地SQLite数据库以确保最新状态。

安装方法

安装WhatsApp MCP服务器需要先安装必要的依赖项，包括Go语言环境、Python 3.6+、UV以及FFmpeg（用于音频处理）。

curl -LsSf https://astral.sh/uv/install.sh | sh

接下来，克隆项目仓库并进入目录：

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

cd whatsapp-mcp

启动Go语言桥梁程序以连接到WhatsApp Web API：

cd whatsapp-bridge && go run main.go

配置MCP服务器，编辑配置文件并设置路径：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server"
      ]
    }
  }
}

使用方法

使用WhatsApp MCP服务器需要启动Go桥梁和Python MCP服务器。以下是具体步骤：

go run bridge/main.go

pip install flask requests
python server/mcp_server.py

服务器启动后，可以通过以下命令与WhatsApp进行交互：

search_contacts(name="张三")
send_message(ph, text="会议取消")

使用示例

以下是几个典型使用场景和示例：

• 搜索最近联系人：输入“搜索最近联系人：张三”，返回张三的联系方式及相关信息。
• 批量发送通知：输入“向所有人发送通知：会议取消”，成功发送通知给所有目标联系人。

技术细节

WhatsApp MCP服务器的请求流程为：Claude -> Python 服务器 -> Go 桥梁 -> WhatsApp API。所有消息存储在SQLite数据库中，确保高效查询。

此外，WhatsApp对设备链接数有限制，建议定期清理不再使用的设备。

注意事项

在使用过程中，需注意以下事项：

• 确保脚本拥有足够的文件访问权限。
• 若PATH环境变量未配置，建议使用全路径执行命令。
• 认证失败时，检查是否已达到WhatsApp的设备限制。

常见问题

以下是几个常见问题及其解决方法：

• 如何解决认证失败的问题？：尝试重新扫描二维码或检查网络连接。
• 为什么有些媒体无法正常显示？：确保媒体文件格式正确且未损坏。
• 是否可以删除旧的聊天记录？：目前不支持直接删除，建议定期清理数据库。

WhatsApp MCP服务器为用户提供了强大的消息处理和AI集成能力，是管理WhatsApp聊天记录和自动化消息交互的理想工具。