🚀 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 即可下载并返回路径。
🔧 技术细节
- 请求流程：Claude -> Python 服务器 -> Go 桥梁 -> WhatsApp API
- 数据存储：所有消息存入 SQLite 数据库，确保高效查询。
- 设备限制：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 文件。