search_contactsLABSCO SUMMARY
Your WhatsApp, searchable, on your own disk.
The archive is local, and the agent sees a chat only when it calls a tool for it. That makes the useful thing possible — finding the message where somebody agreed to something, then replying in the same thread — without handing your history to a third party.
What it is
A TypeScript MCP server that connects to your personal WhatsApp account through the WhatsApp Web multi-device API using Baileys. Messages and auth state live locally in ./data/ and ./auth_info/; material reaches the agent only when it calls a tool.
What you get
- Contacts searched by name or part of a phone number
- Message history for a chat, paginated
- Chats listed, sortable by activity or name, filterable, optionally with last-message detail
- Detail for one specific chat
- The messages immediately before and after a given message ID, when a single hit needs its surroundings
- A text message sent to a person or a group by JID
Requirements
Your own WhatsApp account, linked the way WhatsApp Web links: the session sits in ./auth_info/ and the message archive in a local SQLite database under ./data/. You run it with Node 23.10.0 or later from a clone of the repository. Contact search covers individuals, not groups.
Setup effort
Build from source — git clone https://github.com/aukik/whatsapp-mcp-ts.git whatsapp-mcp-ts
USE CASES
01
Finding the person before you can message them
Search contacts by name or number fragment and get the JID you need to send to.
02
Digging up what was actually agreed
Page through a chat's history, then pull the messages around the one that matters for context.
03
Catching up on what has been active
List chats by recent activity with last-message detail, and open the one that needs attention.
04
Replying without picking up your phone
Send the message to a person or a group from the client you are already working in.
6 tools
Listed in project docs. Your client may show a different list.
list_messageslist_chatsget_chatget_message_contextsend_messageBEFORE YOU INSTALL
What to know first
Tools you get
6 tools named in the project's documentation.
Requires
Node.js Version 23.10.0
Where it runs
Both documented clients run the server on your machine.
INSTALLATION
Connect your client
You clone this one yourself.
Server setup
TERMINAL
git clone https://github.com/aukik/whatsapp-mcp-ts.git whatsapp-mcp-ts
cd whatsapp-mcp-ts
npm install
node src/main.tsOn the first run it opens a QR code link — scan it in the WhatsApp app under Settings > Linked Devices > Link a Device, keep the terminal running until your messages have synced, then close it
MCP Clients
Claude Desktop, Cursor
<YOUR_PATH_TO_REPO> is the absolute path of your clone — run pwd inside the whatsapp-mcp-ts folder to get it.
JSON
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": [
"<YOUR_PATH_TO_REPO>/src/main.ts"
],
"timeout": 15,
"disabled": false
}
}
}
