×

WhatsApp MCP Server

Connect Gemini CLI to WhatsApp in one command.
Read messages · Search contacts · Send texts, images & voice notes — all from your terminal.

✨ What It Does

A Model Context Protocol (MCP) server that bridges your personal WhatsApp account to Gemini CLI. Your AI assistant can now read, search, and send WhatsApp messages — all running locally on your machine.

• 💬 Read & search messages across all your chats
• 👤 Search contacts by name or phone number
• 📤 Send messages to individuals or groups
• 📎 Send & download media — images, videos, documents, voice notes
• 🔒 100% local — messages stay in a local SQLite database, only sent to the LLM when you use a tool
• ⚡ One command to get started

How it works: A Go bridge connects to WhatsApp's multi-device API via whatsmeow, stores messages locally, and exposes a REST API. The Python MCP server translates Gemini CLI tool calls into bridge API requests.

🚀 Quick Start

Prerequisites

| Requirement | Install | |------------|---------| | Go ≥ 1.21 | golang.org/dl | | Python ≥ 3.11 | python.org | | uv (Python pkg manager) | curl -LsSf https://astral.sh/uv/install.sh \| sh | | Gemini CLI | github.com/google-gemini/gemini-cli | | FFmpeg (optional) | Only needed to auto-convert audio to voice notes |

2 Steps — That's It

Step 1 → Clone & setup

git clone https://github.com/akashkumar2k01/whatsapp-gemini-mcp.git
cd whatsapp-gemini-mcp
./setup.sh

This builds the Go bridge, installs Python dependencies, and auto-generates your Gemini CLI config. No manual path editing needed.

Step 2 → Start the bridge

./start.sh

📱 First run only: A QR code image opens automatically — scan it with WhatsApp → Settings → Linked Devices → Link a Device. After pairing, sessions persist for ~20 days.

Done. Open Gemini CLI and start chatting with your WhatsApp data. 🎉

gemini

go env -w CGO_ENABLED=1
./setup.sh

📂 Where Data Lives

All WhatsApp data is stored in ~/.whatsapp-gemini-mcp/ — independent of where you cloned the repo:

| File | Purpose | |------|---------| | whatsapp.db | WhatsApp session & authentication | | messages.db | All your messages (SQLite with WAL mode) | | whatsapp_qr.png | QR code image (only during auth) | | media/ | Downloaded media files |

This means you can clone the repo anywhere, cd into any directory, and everything just works. No "wrong directory" bugs.

🛠 Available Tools

| Tool | Description | |------|-------------| | check_bridge_health | Verify Go bridge is running (use first if issues) | | get_qr_status | Check if QR re-authentication is needed | | search_contacts | Search contacts by name or phone number | | list_chats | List chats with filters, pagination & sorting | | get_chat | Get single chat metadata by JID | | list_messages | Search messages with date/sender/keyword filters | | get_message_context | Get surrounding messages for context | | get_last_interaction | Most recent message with a contact | | get_direct_chat_by_contact | Find DM chat by phone number | | get_contact_chats | All chats involving a contact | | send_message | Send text to a phone number or JID | | send_file | Send image, video, or document | | send_audio_message | Send voice note (auto-converts to ogg/opus) | | download_media | Download media from a message to disk |

JID Format

• Personal: 919876543210@s.whatsapp.net (country code + number)
• Group: 120363XXXXXXXX@g.us

🏗 Architecture

┌───────────────┐       stdio (MCP JSON-RPC)       ┌───────────────────┐
│  Gemini CLI   │◄─────────────────────────────────►│  Python MCP       │
│               │                                    │  Server (main.py) │
└───────────────┘                                    └────────┬──────────┘
                                                              │ HTTP :8080
                                                              ▼
                                                     ┌────────────────────┐
                                                     │  Go WhatsApp       │
                                                     │  Bridge (main.go)  │
                                                     └────────┬───────────┘
                                                              │ whatsmeow
                                                              ▼
                                                     ┌────────────────────┐
                                                     │  WhatsApp Web API  │
                                                     └────────────────────┘

| Component | Role | |-----------|------| | Go Bridge (bridge/) | Connects to WhatsApp via multi-device API, handles QR auth, stores messages in SQLite, serves REST API on :8080 | | Python MCP Server (mcp-server/) | Implements MCP protocol over stdio, translates tool calls to bridge REST calls | | SQLite Store (~/.whatsapp-gemini-mcp/) | Local database for messages, chats, and session data — never leaves your machine |

Data Flow

Send:    Gemini CLI → MCP Server → Go Bridge → WhatsApp API → Recipient
Receive: WhatsApp API → Go Bridge → SQLite → MCP Server → Gemini CLI

📎 Media Handling

Sending Media

| Method | Use Case | |--------|----------| | send_file | Images, videos, documents — any file type | | send_audio_message | Voice notes (auto-converts to ogg/opus with FFmpeg) |

Without FFmpeg, use send_file for audio — it won't appear as a playable voice note, but the file will be sent.

Downloading Media

Media metadata is stored automatically. To download the actual file:

Use the download_media tool with message_id and chat_jid
→ Returns the local file path for viewing or further processing

🔧 Troubleshooting

| Issue | Fix | |-------|-----| | Bridge not reachable | Run check_bridge_health tool, ensure ./start.sh is running | | QR code not showing | QR is saved as ~/.whatsapp-gemini-mcp/whatsapp_qr.png and auto-opened; check the file manually | | WebSocket error on first run | The bridge retries 3 times automatically. Check your internet connection | | Device limit reached | Remove a device in WhatsApp → Settings → Linked Devices | | Messages not loading | Initial history sync can take a few minutes for large accounts | | Out of sync | Delete ~/.whatsapp-gemini-mcp/messages.db and ~/.whatsapp-gemini-mcp/whatsapp.db, restart bridge | | Permission errors with uv | Run which uv and use the full path in config | | Audio conversion fails | Install FFmpeg: brew install ffmpeg (macOS) or apt install ffmpeg (Linux) |

🔒 Security & Privacy

• All data stays local — messages are stored in SQLite on your machine
• No cloud sync — the bridge connects directly to WhatsApp's API
• You control access — set "trust": false in settings to approve each tool call
• Sensitive files — ~/.whatsapp-gemini-mcp/ directory contains your full message history; it's stored in your home directory and excluded from git

📄 License

MIT

If this project helped you, consider giving it a ⭐
_{Built with ❤️ by AKASHKUMAR SENTHIL (AK) — using Go, Python, and the Model Context Protocol}