使用说明

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	github.com/google-gemini/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：

安装 Msys 2 并添加 ucrt64\bin 致你的 PATH (引导)
运行前启用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}