search_contactsLABSCO SUMMARY
Your own WhatsApp, made searchable — and the archive stays on your machine.
The reading is worth as much as the sending here: because the bridge keeps your history in a local database instead of fetching it each time, years of chats turn into something you can ask questions of. Replying, sending files and leaving a voice note then go out over the same connection your phone already trusts, so nothing has to be re-authorised per action.
What it is
A server for a personal WhatsApp account. It links the way WhatsApp Web does, by scanning a code with your phone, and keeps the message history in a local database — so searching years of chats happens on your machine, and only what the agent actually asks for reaches the model.
What you get
- Contacts searched by name or phone number
- Messages listed with filters, and the surrounding context of any single one
- Chats listed with their metadata, opened by contact, or reduced to the last thing exchanged with someone
- Every chat a given contact appears in, direct or group
- Messages sent to a person or to a group
- Files sent — images, video, documents, audio
- Audio sent as a playable voice message rather than an attachment
- Media from a received message downloaded to a local path you can hand to another tool
Requirements
- Your phone, to scan the link code — and to scan again when the link lapses
- Go and Python toolchains. It runs as two processes: a bridge that holds the WhatsApp connection and stores messages, and the server your client talks to. Both have to be up
- On Windows, a C compiler with cgo turned on before the bridge will build — without it the build fails on the local database driver
- For voice messages, audio already in Opus form, or ffmpeg installed so it can convert. Without either you can still send the file, it just will not be playable in the chat
- It reads private messages and can send them, which is the shape prompt injection exploits — the README says so directly. Keep untrusted content out of any conversation this is connected to
Setup effort
Build from source — git clone https://github.com/lharries/whatsapp-mcp.git
USE CASES
01
Finding what somebody actually said months ago
Search the person, open the direct chat, and read the messages around the one that matters instead of scrolling to it on a phone.
02
Picking up a thread you left hanging
Ask when you last spoke to someone and what was said, then reply in the same request.
03
Working out which conversations need you
List the chats with their metadata and look at the recent traffic across them, so triage happens once rather than chat by chat.
04
Getting an attachment out of a chat and into your work
Download the media from the message to a local path, then pass that path to whatever tool needs to read it.
05
Sending something that is not text
Send the document or image to a person or a group, or send audio as a voice message so it plays in the chat rather than arriving as a file.
06
Checking everything one contact has been part of
List every chat that contact appears in, groups included, before you decide where to reply.
12 tools
Listed in project docs. Your client may show a different list.
list_messageslist_chatsget_chatget_direct_chat_by_contactget_contact_chatsget_last_interactionget_message_contextsend_messagesend_filesend_audio_messagedownload_mediaBEFORE YOU INSTALL
What to know first
Tools you get
12 tools named in the project's documentation.
Requires
- Go
- Python 3.6+
- uv, installed with curl -LsSf https://astral.sh/uv/install.sh | sh
- A C compiler with CGO enabled on Windows — go-sqlite3 will not build without it
- Your phone with WhatsApp, to scan the QR code the bridge shows on first run
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
This one is built from source rather than installed with a single command.
Server setup
Clone this repository
TERMINAL
git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcpRun the WhatsApp bridge
TERMINAL
cd whatsapp-bridge
go run main.goMCP Clients
Claude Desktop, Cursor
JSON
{
"mcpServers": {
"whatsapp": {
"command": "<YOUR_PATH_TO_UV>",
"args": [
"--directory",
"<YOUR_PATH_TO_SRC>/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}<YOUR_PATH_TO_UV> is the output of which uv, and <YOUR_PATH_TO_SRC> is the folder you ran git clone in — the one that now holds whatsapp-mcp. The WhatsApp bridge from the steps has to be running too.
