by lharries
An MCP server that connects Claude to your personal WhatsApp account for searching, reading, and sending messages, media, and voice notes, with everything stored locally.
Clone and run the bridge
git clone https://github.com/lharries/whatsapp-mcp.git && cd whatsapp-mcp/whatsapp-bridge && go run main.go
About
whatsapp-mcp is a two-part system: a Go bridge that logs into WhatsApp's own web multidevice API (via the whatsmeow library) using a QR-code pairing, and stores your message history in a local SQLite database; and a Python MCP server that reads from that database and exposes it as tools. Messages, including images, videos, documents, and audio, never pass through a third-party server. They sit locally until the agent explicitly calls a tool to fetch or search them, at which point only that specific result reaches the LLM.
On the read side it covers contact search, chat listing, message search with filters, and context-around-a-message lookups so an agent can follow a thread rather than see it out of order. On the write side it can send text messages, share files (images, video, documents), and send voice notes by converting audio to WhatsApp's expected Opus/.ogg format, so an agent can hold an actual two-way WhatsApp conversation on your behalf rather than just read history.
Key features
- Direct connection to your personal WhatsApp account via the web multidevice API, no third-party relay
- Local SQLite storage, message history never leaves your machine except per-tool-call results
- Full-text and filtered search across chats, contacts, and message history
- Sends text, media files, and voice notes (auto-converted to Opus/.ogg)
- Context-around-a-message retrieval for following a conversation thread
- Media download tool that returns a local file path for images, video, and documents
Use cases
- Letting Claude draft and send WhatsApp replies to specific contacts based on message history
- Searching years of WhatsApp history for a specific document, decision, or conversation thread
- Building a personal WhatsApp assistant that summarizes unread messages or drafts responses
- Automating routine WhatsApp replies (confirmations, forwarding a file) without opening the app
Available tools
search_contacts
Finds contacts by name or phone number.
list_messages
Retrieves messages with optional filters (chat, date, sender).
send_message
Sends a text message to an individual or group.
send_file
Shares an image, video, or document to a chat.
send_audio_message
Sends an audio file as a WhatsApp voice note, converting it to Opus/.ogg.
download_media
Downloads media from a message and returns its local file path.
Frequently asked questions
Does WhatsApp data pass through any third-party server?
No. The Go bridge talks directly to WhatsApp's own web API and stores everything in a local SQLite database; only the specific message or result a tool call returns is sent to the LLM.
How do I authenticate WhatsApp?
By scanning a QR code with your phone the first time the Go bridge runs, the same pairing flow WhatsApp Web itself uses.