×
WhatsApp MCP Server
Connect Gemini CLI to WhatsApp in one command.
Read messages · Search contacts · Send texts, images & voice notes — all from your terminal.
______________________________________________________________________
✨ 它的作用
A. 模型上下文协议（MCP） 将您的个人WhatsApp帐户连接到的服务器 Gemini CLI。你的人工智能助手现在可以阅读、搜索和发送WhatsApp消息——所有这些都在你的机器上本地运行。
- 💬 阅读和搜索 您所有聊天记录中的消息
- 👤 搜索联系人 按姓名或电话号码
- 📤 发送消息 个人或团体
- 📎 发送和下载媒体 --图像、视频、文档、语音备忘
- 🔒 100%本地 --消息保留在本地SQLite数据库中，仅在使用工具时发送到LLM
- ⚡ 一个命令 开始
它是如何工作的： Go桥接通过连接到WhatsApp的多设备API 怎么回事，在本地存储消息，并公开REST API。Python MCP服务器将Gemini CLI工具调用转换为桥接API请求。
______________________________________________________________________
🚀 快速开始
先决条件
| 要求 | 安装 | |
|---|---|---|
| 去 ≥ 1.21 | golang.org/dl | |
| python ≥ 3.11 | python.org | |
| 紫外线 （Python pkg管理器） | `curl -LsSf https://astral.sh/uv/install.sh \ | sh` |
| Gemini CLI | ||
| FFmpeg *（可选）* | 只需要将音频自动转换为语音备忘 |
两步——就是这样
步骤1→ 克隆和设置
git clone https://github.com/akashkumar2k01/whatsapp-gemini-mcp.git
cd whatsapp-gemini-mcp
./setup.sh这将构建Go桥，安装Python依赖项，并自动生成Gemini CLI配置。 无需手动编辑路径。
步骤2→ 启动桥梁
./start.sh📱 仅限首次运行： 二维码图像会自动打开——用 WhatsApp→ 设置→ 链接设备→ 链接设备配对后，会话持续约20天。
完成。 打开Gemini CLI，开始与您的WhatsApp数据聊天。 🎉
gemini📋 What setup.sh does
- ✅ 检查先决条件（Go、Python、uv）
- 📁 创造
~/.whatsapp-gemini-mcp/数据目录 - 🔨 构建Go桥二进制文件
- 📦 通过以下方式安装Python依赖项
uv sync - ⚙️ 自动生成
~/.gemini/settings.json使用WhatsApp MCP配置 - 🔄 如果您使用的是旧版本，则迁移现有会话数据
🪟 Windows users — extra CGO step
go-sqlite3 需要Windows上的CGO：
go env -w CGO_ENABLED=1
./setup.sh______________________________________________________________________
📂 数据所在之处
所有WhatsApp数据都存储在 ~/.whatsapp-gemini-mcp/ --与您克隆repo的位置无关：
| 文件 | 目的 |
|---|---|
whatsapp.db | WhatsApp会话和身份验证 |
messages.db | 您的所有消息（带WAL模式的SQLite） |
whatsapp_qr.png | 二维码图像（仅在身份验证期间） |
media/ | 已下载的媒体文件 |
这意味着你可以在任何地方克隆仓库， cd 进入任何目录，一切正常。没有“错误目录”错误。______________________________________________________________________
🛠 可用工具
| 工具 | 说明 |
|---|---|
check_bridge_health | 验证Go桥是否正在运行 *（如有问题，请先使用）* |
get_qr_status | 检查是否需要QR重新验证 |
search_contacts | 按姓名或电话号码搜索联系人 |
list_chats | 使用过滤器、分页和排序列出聊天记录 |
get_chat | 通过JID获取单聊天元数据 |
list_messages | 使用日期/发件人/关键字过滤器搜索邮件 |
get_message_context | 获取周围的消息以获取上下文 |
get_last_interaction | 联系人的最新消息 |
get_direct_chat_by_contact | 通过电话号码查找DM聊天 |
get_contact_chats | 所有涉及联系人的聊天 |
send_message | 向电话号码或JID发送文本 |
send_file | 发送图像、视频或文档 |
send_audio_message | 发送语音备忘（自动转换为ogg/opus） |
download_media | 将媒体从邮件下载到磁盘 |
JID格式
- 个人的：
919876543210@s.whatsapp.net（国家代码+编号） - 组：
120363XXXXXXXX@g.us
______________________________________________________________________
🏗 建筑
┌───────────────┐ stdio (MCP JSON-RPC) ┌───────────────────┐
│ Gemini CLI │◄─────────────────────────────────►│ Python MCP │
│ │ │ Server (main.py) │
└───────────────┘ └────────┬──────────┘
│ HTTP :8080
▼
┌────────────────────┐
│ Go WhatsApp │
│ Bridge (main.go) │
└────────┬───────────┘
│ whatsmeow
▼
┌────────────────────┐
│ WhatsApp Web API │
└────────────────────┘| 组件 | 角色 |
|---|---|
Go Bridge (bridge/) | 通过多设备API连接到WhatsApp，处理QR验证，在SQLite中存储消息，在上提供REST API :8080 |
Python MCP服务器 (mcp-server/) | 通过stdio实现MCP协议，将工具调用转换为桥接REST调用 |
SQLite商店 (~/.whatsapp-gemini-mcp/) | 用于消息、聊天和会话数据的本地数据库——永远不会离开您的计算机 |
数据流
Send: Gemini CLI → MCP Server → Go Bridge → WhatsApp API → Recipient
Receive: WhatsApp API → Go Bridge → SQLite → MCP Server → Gemini CLI______________________________________________________________________
📎 媒体处理
发送媒体
| 方法 | 用例 |
|---|---|
send_file | 图像、视频、文档——任何文件类型 |
send_audio_message | 语音备忘（使用FFmpeg自动转换为ogg/opus） |
如果没有FFmpeg，请使用 send_file 对于音频，它不会显示为可播放的语音备忘，但文件会被发送。下载媒体
媒体元数据会自动存储。要下载实际文件，请执行以下操作：
Use the download_media tool with message_id and chat_jid
→ Returns the local file path for viewing or further processing______________________________________________________________________
🔧 故障排除
| 问题 | 修复 |
|---|---|
| 无法到达桥梁 | 快跑 check_bridge_health 工具，确保 ./start.sh 正在运行 |
| 二维码未显示 | QR另存为 ~/.whatsapp-gemini-mcp/whatsapp_qr.png 并自动打开；手动检查文件 |
| 首次运行时发生WebSocket错误 | 网桥会自动重试3次。检查您的互联网连接 |
| 已达到设备限制 | 在WhatsApp中删除设备→ 设置→ 链接设备 |
| 邮件未加载 | 对于大型帐户，初始历史同步可能需要几分钟时间 |
| 不同步 | 删除 ~/.whatsapp-gemini-mcp/messages.db 和 ~/.whatsapp-gemini-mcp/whatsapp.db，重新启动网桥 |
| uv权限错误 | 快跑 which uv 并在配置中使用完整路径 |
| 音频转换失败 | 安装FFmpeg： brew install ffmpeg （macOS）或 apt install ffmpeg （Linux） |
______________________________________________________________________
🔒 安全与隐私
- 所有数据都保留在本地 --消息存储在您计算机上的SQLite中
- 无云同步 -该桥直接连接到WhatsApp的API
- 您控制访问权限 --set
"trust": false在设置中批准每个工具调用 - 敏感文件 —
~/.whatsapp-gemini-mcp/目录包含您的完整消息历史记录；它存储在您的主目录中，并从git中排除
______________________________________________________________________
📄 许可证
麻省理工学院
______________________________________________________________________
If this project helped you, consider giving it a ⭐
Built with ❤️ by AKASHKUMAR SENTHIL (AK) — using Go, Python, and the Model Context Protocol