使用说明

项目简介

WhatsApp MCP服务器是一个基于Model Context Protocol (MCP) 的后端应用，它充当LLM（如Claude）与用户的个人WhatsApp账户之间的桥梁。通过这个服务器，LLM可以安全地访问用户的WhatsApp数据，执行搜索、读取消息、发送消息和媒体文件等操作，从而实现更智能的WhatsApp自动化和集成。所有消息都本地存储在SQLite数据库中，确保用户数据隐私和安全。

主要功能点

搜索和读取WhatsApp消息: 包括文本、图片、视频、文档和音频消息。
搜索联系人: 根据姓名或电话号码查找WhatsApp联系人。
发送消息: 向个人或群组发送文本和媒体消息。
发送媒体文件: 支持发送图片、视频、文档和音频文件，音频文件支持转换为WhatsApp语音消息格式。
媒体文件下载: 下载WhatsApp消息中的媒体文件到本地。
本地数据存储: 所有WhatsApp消息和联系人信息都存储在本地SQLite数据库中，保护用户隐私。
工具化操作: 提供一系列预定义的工具，如 'search_contacts', 'list_messages', 'send_message' 等，方便LLM客户端调用。

安装步骤

克隆仓库

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

运行 WhatsApp Bridge

进入 'whatsapp-bridge' 目录，并运行 Go 应用：
```
cd whatsapp-bridge
go run main.go
```
首次运行时，会提示扫描二维码。使用您的 WhatsApp 移动应用扫描二维码进行身份验证。

大约每 20 天可能需要重新验证身份。

连接到 MCP 服务器

复制以下 JSON 配置，并根据您的环境修改 '{{PATH_TO_UV}}' 和 '{{PATH_TO_SRC}}' 的值：

{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // 运行 'which uv' 并将输出路径填写在此处
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp-server", //  cd 到仓库根目录，运行 'pwd' 并将输出路径填写在此处 + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}

对于 Claude: 将上述 JSON 保存为 'claude_desktop_config.json'，并放置在 Claude Desktop 配置目录下： '~/Library/Application Support/Claude/claude_desktop_config.json' (macOS) 或 '%APPDATA%\Claude' (Windows)。
对于 Cursor: 将上述 JSON 保存为 'mcp.json'，并放置在 Cursor 配置目录下： '~/.cursor/mcp.json' (macOS/Linux) 或 '%USERPROFILE%.cursor' (Windows)。

重启 Claude Desktop / Cursor

重启 Claude Desktop 或 Cursor，您应该能在集成选项中看到 WhatsApp。

服务器配置

MCP客户端需要配置MCP服务器的启动命令及其参数，以下是配置示例，请根据实际路径进行修改：

{
  "mcpServers": {
    "whatsapp": {
      "command": "/Users/your_username/.local/bin/uv",  // 请替换为 uv 的实际路径，例如通过运行 'which uv' 获取
      "args": [
        "--directory",
        "/path/to/whatsapp-mcp-server/whatsapp-mcp-server", // 请替换为 whatsapp-mcp-server 目录的实际路径，例如通过在仓库根目录运行 'pwd' 获取
        "run",
        "main.py"
      ]
    }
  }
}

配置说明:

'"command"': MCP服务器的启动命令，这里使用 'uv run main.py' 运行 Python 代码。请确保替换为 'uv' 包管理器的实际路径。
'"args"': 启动命令的参数列表。
- '--directory': 指定 MCP 服务器 Python 代码所在的目录。请确保替换为 'whatsapp-mcp-server' 目录的实际绝对路径。
- 'run main.py': 使用 'uv run' 命令执行 'main.py' 文件，启动 MCP 服务器。

注意: 请根据您的操作系统和 Python 环境，确保 'uv' 和 Python 环境配置正确，并且路径设置正确。

基本使用方法

成功连接后，您可以在 Claude 或 Cursor 等 MCP 客户端中使用以下工具与 WhatsApp 进行交互：

'search_contacts(query)': 搜索联系人，'query' 为搜索关键词。
'list_messages(query, chat_jid, limit)': 列出消息，可根据关键词 'query'、聊天 JID 'chat_jid' 过滤，并限制返回数量 'limit'。
'list_chats(query, limit)': 列出聊天列表，可根据关键词 'query' 过滤，并限制返回数量 'limit'。
'send_message(recipient, message)': 发送文本消息，'recipient' 为接收方电话号码或群组 JID，'message' 为消息内容。
'send_file(recipient, media_path)': 发送文件，'recipient' 为接收方，'media_path' 为本地文件路径。
'download_media(message_id, chat_jid)': 下载媒体文件，'message_id' 和 'chat_jid' 从消息元数据中获取。

在 Claude 或 Cursor 中，您可以直接在对话中使用这些工具，例如：

@whatsapp search_contacts(query="张三")
@whatsapp list_messages(chat_jid="[email protected]", limit=5)
@whatsapp send_message(recipient="11234567890", message="你好！")

具体工具的使用方法和参数，请参考每个工具的描述信息。

关键词