🚀 WhatsApp MCP 协议服务器

本项目是一个用于与 WhatsApp 交互的 MCP（模型上下文协议）服务器，系统包含 Go 语言桥梁和 Python MCP 服务器两大组件。前者负责对接 WhatsApp API 并存储消息历史，后者实现 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 文件。