WhatsApp MCP 协议服务器

项目概述

这是一个用于与 WhatsApp 交互的 MCP（模型上下文协议）服务器。该系统包含两个主要组件：

1. Go语言桥梁：负责与 WhatsApp API 对接，并维护 SQLite 数据库，存储所有消息历史。
2. Python MCP 服务器：实现 MCP 协议，提供标准化工具供 Claude 使用。

安装与运行

下载代码

使用 Git 克隆项目仓库：

git clone https://github.com/your-username/whatsapp-mcp.git

进入 WhatsApp-MCP 目录：

cd whatsapp-mcp

运行 Go 桥梁

启动桥梁之前，确保安装了 Go 语言环境。然后在终端运行以下命令：

go run bridge/main.go

启动 Python MCP 服务器

该服务器使用 Flask 框架实现。首先安装依赖项：

pip install flask requests

然后运行服务器：

python server/mcp_server.py

核心功能

数据存储

• 数据库位置：whatsapp-bridge/store/
• 聊天记录：所有消息按时间顺序存储，并支持快速搜索和检索。
• 索引优化：通过 SQLite 的查询优化技术，提升数据访问效率。

MCP 工具

Claude 可以通过以下工具与 WhatsApp 交互：

搜索功能

• search_contacts：根据姓名或号码查找联系人。
• list_messages：检索消息，支持过滤和上下文扩展。
• list_chats：列出所有可用聊天记录，含元数据。

联系人操作

• get_chat：获取特定聊天的详细信息。
• get_direct_chat_by_contact：查找与指定联系人的直接对话。
• get_contact_chats：列举特定联系人参与的所有聊天。

消息处理

• get_last_interaction：获取与某个联系人的最新消息。
• get_message_context：获取某条消息的上下文信息。

发送功能

• send_message：向指定号码或群组发送文本消息。
• send_file：发送图片、视频、文档等文件。
• send_audio_message：发送音频消息，需确保为 .ogg 格式或安装 FFmpeg 进行格式转换。

媒体管理

• download_media：下载指定消息中的媒体文件，并返回本地路径。

媒体处理

发送规则

• 支持类型：图片、视频、文档等可通过 send_file 发送。
• 音频发送：使用 send_audio_message 工具，需 .ogg 格式或 FFmpeg 转换。

下载功能

默认仅存储媒体的元数据。要获取实际文件，请使用 download_media 工具，输入 message_id 和 chat_jid 即可下载并返回路径。

技术细节

1. 请求流程：Claude -> Python 服务器 -> Go 桥梁 -> WhatsApp API
2. 数据存储：所有消息存入 SQLite 数据库，确保高效查询。
3. 设备限制：WhatsApp 设备链接数有限制，请定期清理不再使用的设备。

故障排除

• 权限问题：确保脚拥有足够的文件访问权限。若 PATH 环境变量未配置，建议使用全路径执行命令。
• 认证失败：检查是否已达到 WhatsApp 的设备限制，可通过手机设置 -> 链接设备管理清理旧设备。

附录

示例代码

Go 桥梁启动

package main

import (
    "fmt"
    "log"
)

func main() {
    fmt.Println("WhatsApp Bridge Started")
    // 数据库初始化逻辑
}

Python 服务器运行

from flask import Flask
import requests

app = Flask(__name__)

@app.route('/api/send_message', methods=['POST'])
def send_message():
    # 处理消息发送逻辑
    return "Message Sent"

命令行示例

启动桥梁：

go run bridge/main.go

运行服务器：

python server/mcp_server.py

许可证

本项目遵循 MIT 许可证，具体内容请参阅 LICENSE 文件。