search_contactsLABSCO SUMMARY
Your WhatsApp history, queryable and local.
It connects to your own account through the multidevice web API and keeps the messages in a SQLite file on your machine, so searching a two-year thread is a local query rather than an upload.
What it is
A two-part server: a Go bridge that connects to WhatsApp's multidevice web API and stores messages in local SQLite, and a Python MCP server that queries it. History loads lazily rather than all at once.
What you get
- Contacts searched by name or number
- Personal messages searched and read, including images, video, documents and audio
- The last interaction with a given contact, without paging through the thread
- Messages and media sent to individuals or groups — images, video, documents and voice notes
- Everything stored locally in SQLite, with queries tuned for large histories
Requirements
Go 1.24.1+, Python 3.11+, uv and the Claude Desktop app. FFmpeg is optional and only needed for audio. The Go bridge authenticates by QR scan on first run and has to stay running while you use it.
Setup effort
Build from source — git clone https://github.com/Charlesagui/mcp-whats-app.git
USE CASES
01
Finding the message where something was agreed
Search the stored history instead of scrolling a thread on your phone.
02
Picking up a conversation you dropped
The last interaction with a contact, so you know where it was left before you reply.
03
Sending a file to a group
Find the contact or group, then send images, documents, video or a voice note from the same session.
04
Pulling context out of an old thread
Media and text both come back, so the attachment someone sent last March is findable rather than lost in the scroll.
8 tools
Listed in project docs. Your client may show a different list.
list_messagesget_last_interactionget_message_contextsend_messagesend_filesend_audio_messagedownload_mediaBEFORE YOU INSTALL
What to know first
Tools you get
8 tools named in the project's documentation.
Requires
- Go 1.24.1+
- Python 3.11+
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
This one is built from source rather than installed with a single command.
Server setup
TERMINAL
git clone https://github.com/Charlesagui/mcp-whats-app.git
cd mcp-whats-appRun instalar-dependencias.bat once (installs the Go and Python dependencies and creates .env from .env.example)
Without the .bat script (macOS / Linux), run the next three commands instead
TERMINAL
cp .env.example .env
cd whatsapp-bridge && go mod tidy
cd ../whatsapp-mcp-server && uv syncAdd the mcpServers entry below to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json)
In that entry, <YOUR_PATH_TO_UV> is the full path to uv (run which uv to print it) and <YOUR_PATH_TO_SRC>/mi-whatsapp-mcp is the full path of your mcp-whats-app clone (cd into it and run pwd)
Start the bridge and keep it open — iniciar-whatsapp-bridge.bat on Windows, or go run main.go inside whatsapp-bridge elsewhere; the first run shows a QR code
Scan the QR code with the WhatsApp mobile app
Restart Claude Desktop
MCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"whatsapp": {
"command": "<YOUR_PATH_TO_UV>",
"args": [
"--directory",
"<YOUR_PATH_TO_SRC>/mi-whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}
