这是一个基于 Model Context Protocol (MCP) 的 WhatsApp 服务器实现，旨在将您的 WhatsApp 账户能力暴露给支持 MCP 的大型语言模型 (LLM) 客户端，例如 Claude Desktop。

该项目包含两个主要部分：

Go WhatsApp Bridge: 负责连接到您的 WhatsApp 账户，处理认证（通过二维码扫描），并将消息历史、联系人信息等存储到 SQLite 数据库。它还提供一个内部的 REST API 供 MCP 服务器调用。
Python MCP Server: 实现了 MCP 协议。它接收来自 LLM 客户端的 MCP 请求（通过标准输入/输出 - Stdio），将这些请求转换为对 Go Bridge 内部 API 的调用或直接查询数据库，然后将结果格式化为 MCP 响应返回给客户端。

主要功能点:

访问消息: 搜索和读取您个人的 WhatsApp 消息，包括文字和媒体（图片、视频、文档、语音）。
管理联系人: 搜索您的联系人列表。
发送消息: 向个人或群组发送文本消息。
发送文件: 发送图片、视频、文档、原始音频文件。
发送语音消息: 发送任何音频文件作为 WhatsApp 语音消息（需要安装 FFmpeg）。
下载媒体: 从 WhatsApp 消息中下载媒体文件到本地。
获取聊天列表: 查看您当前的所有聊天列表。
数据本地存储: 所有消息历史都安全地存储在您的本地计算机上。

安装步骤:

克隆仓库:

git clone https://github.com/Charlesagui/mcp-whats-app.git
cd mcp-whats-app

安装 Go 和 Python: 确保您的系统已安装 Go (1.24.1+) 和 Python (3.11+)。
安装 FFmpeg (可选): 如果需要发送语音消息，请安装 FFmpeg 并确保它在系统 PATH 中。

安装 Python 依赖: 使用 UV (或 pip) 安装 MCP 服务器的依赖。

# 安装 uv (如果尚未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 进入 Python MCP 服务器目录并安装依赖
cd whatsapp-mcp-server
uv sync # 或者 pip install -r requirements.txt
cd .. # 返回项目根目录

运行 WhatsApp Bridge:
```
cd whatsapp-bridge
go run main.go
```
首次运行时，它会生成一个二维码，您需要用手机上的 WhatsApp 扫描该二维码以链接设备。一旦连接成功，桥接程序会开始同步您的消息历史。保持此窗口或进程运行。

配置 MCP 客户端 (例如 Claude Desktop): LLM 客户端需要知道如何启动和连接到这个 MCP 服务器。您需要在客户端的配置中添加 MCP 服务器的信息。对于 Claude Desktop，通常是在其配置文件 ('claude_desktop_config.json') 的 'mcpServers' 部分添加一个条目。

配置信息示例如下（请根据您的实际项目路径替换 '[项目根目录]'）：

{
  "mcpServers": {
    "whatsapp": {
      "command": "python",  // 启动 MCP 服务器的命令，这里是 Python 解释器
      "args": [
        "[项目根目录]/whatsapp-mcp-server/main_fixed.py" // MCP 服务器主脚本的绝对路径
      ],
      "env": {
         "PYTHONPATH": "[项目根目录]/whatsapp-mcp-server" // 设置 Python 模块搜索路径
      }
    }
    // 您可能还有其他 MCP 服务器的配置
  }
}

请根据您的操作系统找到 'claude_desktop_config.json' 文件（例如 Windows 在 '%APPDATA%\Claude'，macOS 在 '~/Library/Application Support/Claude/'，Linux 在 '~/.config/Claude/'），并编辑它添加上述 'whatsapp' 条目。请确保 'command' 和 'args' 中的路径是正确的。您可以使用项目中的 'mcp-server/configure_claude_simple.py' 脚本来自动化这个配置过程（仅限 Windows）。

运行 MCP 服务器: 按照您在客户端配置中指定的命令启动 Python MCP 服务器。如果使用项目中的启动脚本，则是在项目根目录运行：
```
python iniciar_completo.py
```
这个脚本会同时启动 Go Bridge 和 Python MCP Server，并在 Windows 上可能在单独的窗口中运行。MCP 服务器启动后，会通过标准输入/输出等待 LLM 客户端的连接。
重启 MCP 客户端: 保存客户端配置文件并重启您的 LLM 客户端（如 Claude Desktop）。客户端应该会自动发现并连接到运行中的 WhatsApp MCP 服务器。

基本使用方法:

一旦 MCP 服务器成功连接到您的 LLM 客户端，您就可以通过自然语言与客户端交互来使用 WhatsApp 功能了。例如，在 Claude Desktop 中，您可以尝试：

询问 WhatsApp 的连接状态：'Cuál es el estado de WhatsApp?' (或者使用客户端支持的语言)
列出最近的 WhatsApp 消息：'Lista mis últimos mensajes de WhatsApp.'
搜索联系人：'Busca contactos de WhatsApp llamados [联系人姓名]。'
发送消息：'Envía un WhatsApp a [联系人姓名/电话号码] diciendo [你的消息内容]。'
列出聊天：'Lista mis chats de WhatsApp.'
下载媒体：如果 LLM 在消息中识别到媒体（可能需要工具调用），您可以指示它下载：'Descarga la imagen/video del mensaje [消息ID] del chat [聊天JID]' (这取决于 LLM 如何调用 'download_media' 工具)。

确保 Go Bridge 和 Python MCP Server 进程都在运行，MCP 客户端才能正常使用这些功能。

关键词

信息