WhatsApp MCP Server (lharries)
Connect your personal WhatsApp: search, read and send messages and media locally
Add to your client
Copy the config for your MCP client and paste it into its config file.
git clone https://github.com/lharries/whatsapp-mcp && cd whatsapp-mcp/whatsapp-bridge && go run main.goPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"whatsapp-mcp-server-lharries": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/whatsapp-mcp/whatsapp-mcp-server",
"run",
"main.py"
]
}
}
}Before you start
- Go (to build and run the WhatsApp bridge)
- Python 3.6+ and the uv package manager (for the MCP server)
- Claude Desktop or Cursor as the MCP client
- A phone with WhatsApp installed to scan the linking QR code (an available device-link slot)
- FFmpeg (optional) — required only for sending audio as proper WhatsApp voice messages
About WhatsApp MCP Server (lharries)
WhatsApp MCP Server (lharries) connects an MCP client to your personal WhatsApp account so an assistant can search, read, and send your messages and media — all running locally on your own machine. It links to your account the same way WhatsApp Web does (by scanning a QR code), with no business API or cloud relay involved.
It has a two-part architecture: a Go bridge built on the whatsmeow library connects to WhatsApp's web multidevice API and stores your message history in a local SQLite database, and a Python MCP server reads from that database and exposes the MCP tools. Your messages stay on disk in whatsapp-bridge/store/ and are only shared with the LLM when a tool explicitly accesses them.
It can search contacts, list and read chats and message history, retrieve conversation context, send text messages and files to individuals or groups, send audio voice messages, and download media (images, video, documents, audio). FFmpeg is optional but needed to convert audio into the format WhatsApp voice messages require.
Tools & capabilities (12)
search_contactsSearch your contacts by name or number
list_chatsList available chats with metadata
list_messagesRetrieve messages, with filters and context
get_chatGet metadata about a specific chat
get_direct_chat_by_contactFind a direct chat with a specific contact
get_contact_chatsList all chats involving a specific contact
get_last_interactionGet the most recent message with a contact
get_message_contextRetrieve messages around a given message
send_messageSend a text message to a person or group
send_fileSend an image, video, or document
send_audio_messageSend an audio voice message (requires FFmpeg for conversion)
download_mediaDownload media (image/video/document/audio) from a message
When to use it
- Use it when you want an assistant to search and summarize your WhatsApp conversation history
- Use it to send messages or files to individual contacts or groups from inside Claude/Cursor
- Use it to look up a contact and pull the context around a specific message
- Use it to send voice messages or download received media programmatically
- Use it when you specifically need data kept local — messages live in a SQLite DB on your machine, not a cloud service
Quick setup
- 1Clone the repo
- 2Start the Go bridge: `cd whatsapp-bridge && go run main.go`
- 3Scan the printed QR code with WhatsApp on your phone to link the device
- 4Add the Python MCP server to your Claude/Cursor config with the correct paths (run via uv)
- 5Restart Claude Desktop / Cursor and verify with list_chats or search_contacts
Security notes
Authenticates against your personal WhatsApp via the unofficial web multidevice API (QR pairing), which can risk account flags and stores your full chat history in a local unencrypted SQLite DB — protect the data files and the host machine.
WhatsApp MCP Server (lharries) FAQ
Does this use the WhatsApp Business API?
No. It links to your personal account via WhatsApp's web multidevice API (the same mechanism as WhatsApp Web), using the whatsmeow Go library — no Business API or paid cloud service.
Where are my messages stored?
Locally, in a SQLite database under whatsapp-bridge/store/. They're only sent to the LLM when a tool reads them.
Why do I have to re-link every few weeks?
WhatsApp's multidevice sessions expire roughly every 20 days, so you'll periodically re-scan the QR code to re-authenticate.
Why is my message history empty right after linking?
History syncs after the initial link and can take several minutes for large chats to fully populate the local database.
Can it send to groups and send media?
Yes — send_message works for individuals or groups, and send_file / send_audio_message / download_media handle images, video, documents, and audio (FFmpeg needed for voice-message conversion).
Alternatives to WhatsApp MCP Server (lharries)
Powerful Slack MCP with stdio/SSE/HTTP, DMs, group DMs and no-admin token auth
Full Telegram user-account MCP via MTProto: read chats, manage groups, send messages
Gmail MCP with auto OAuth: send, search, label and manage email
Compare WhatsApp MCP Server (lharries) with: