search_contactsLABSCO SUMMARY
The daemon has to be running for messages to be recorded, and that is the constraint to plan around.
Events only reach SQLite while serve is alive; after a gap, WhatsApp's own multidevice retention decides what can be recovered, and request_sync backfills a specific chat for shorter gaps. The author is direct about the security shape too: this is exactly the lethal-trifecta setup, so prompt injection arriving in an incoming message is a real exfiltration path, and log redaction is described as obfuscation rather than anonymisation.
What it is
A single-binary Go server wrapping whatsmeow to expose a personal WhatsApp account. It runs as a long-lived HTTP daemon on 127.0.0.1:8765 that MCP clients connect to, so closing and reopening your client reconnects rather than respawning a process. Messages are cached in local SQLite and only travel to the model when a tool is called.
What you get
- Reading:
search_contacts,list_messageswith context windows,list_chats,get_chat,get_message_context,download_media, andrequest_syncto backfill one chat's history on demand - Sending:
send_message,send_filewith an optional view-once flag,send_audio_message,send_contact_card, and polls viasend_poll,send_poll_voteandget_poll_results - Message actions:
mark_read,mark_chat_read,send_reaction,send_reply,edit_message,delete_messageandsend_typing - Groups:
create_group,leave_group,list_groups,get_group_info,update_group_participantsfor add, remove, promote and demote,set_group_name,set_group_topic,set_group_announce,set_group_locked,get_group_invite_linkandjoin_group_with_link - Blocklist and privacy:
get_blocklist,block_contact,unblock_contact,send_presence,get_privacy_settings,set_privacy_settingandset_status_message - Admin:
is_on_whatsappbatch-checks numbers,get_statusreports the connection, andpairing_statusreturns a structured setup state including the linking QR
Requirements
Go 1.25+ to build (make build writes ./bin/whatsapp-mcp); the runtime needs only the binary. Pair once by starting the daemon and opening http://127.0.0.1:8765/pair to scan the QR with WhatsApp on your phone — the session persists to store/whatsapp.db and needs re-pairing roughly every 20 days. Clients connect over HTTP to http://127.0.0.1:8765/mcp. WHATSAPP_MCP_MEDIA_ROOT sets the only directory files may be read from or written to, defaulting to ./store/uploads/. -allow-remote requires WHATSAPP_MCP_TOKEN. ffmpeg is optional, needed only to convert non-Opus audio for voice notes. Windows requires CGO.
Setup effort
Build from source — git clone https://github.com/Sealjay/mcp-whatsapp.git
USE CASES
01
Finding something someone told you weeks ago
Search the local cache and read the messages around the hit rather than scrolling the phone.
02
Sending a reply from where you are working
Reply in the thread, react, or correct what you just sent, without picking up the phone.
03
Running a group
Add or promote participants, change the subject, or reset the invite link.
04
Asking a group to choose
Send a poll, then read the tally including the options nobody picked.
05
Filling a gap after the daemon was down
Trigger a per-chat backfill instead of waiting to see what turns up.
42 tools
Listed in project docs. Your client may show a different list.
list_messageslist_chatsget_chatget_message_contextdownload_mediarequest_syncsend_messagesend_filesend_audio_messagesend_pollsend_poll_voteget_poll_resultssend_contact_cardmark_readmark_chat_readsend_reactionsend_replyedit_messagedelete_messagesend_typingcreate_groupleave_grouplist_groupsget_group_infoupdate_group_participantsset_group_nameset_group_topicset_group_announceset_group_lockedget_group_invite_linkjoin_group_with_linkget_blocklistblock_contactunblock_contactsend_presenceget_privacy_settingsset_privacy_settingset_status_messageis_on_whatsappget_statuspairing_statusBEFORE YOU INSTALL
What to know first
Tools you get
42 tools named in the project's documentation. subscribe_presence, a profile-photo setter and community or newsletter tools are deferred and not exposed yet.
Requires
Go 1.25+
INSTALLATION
Connect your client
This one is built from source rather than installed with a single command.
Server setup
Prerequisites: Go 1.25+ (build-time only), an MCP client that speaks HTTP, optionally FFmpeg (only for send_audio_message on non-.ogg input). Windows additionally requires CGO and a C compiler
TERMINAL
git clone https://github.com/Sealjay/mcp-whatsapp.git
cd mcp-whatsapp
make build # writes ./bin/whatsapp-mcpStart the daemon: ./bin/whatsapp-mcp serve (listens on 127.0.0.1:8765)
Pair your phone once: open http://127.0.0.1:8765/pair and scan the QR with WhatsApp (Settings -> Linked Devices -> Link a Device). Headless alternative: ./bin/whatsapp-mcp login renders the QR in the terminal
Add the mcpServers block to your client — Claude Desktop uses {"url": ...}; Claude Code (.mcp.json at your project root) and Cursor (~/.cursor/mcp.json) use {"type": "http", "url": ...}
Restart the client
Optional: run the daemon persistently via the launchd plist (docs/launchd/), the systemd user unit (docs/systemd/), or a Claude Code SessionStart hook (docs/hooks/setup.sh)
MCP Clients
Claude Code, Cursor
JSON
{
"mcpServers": {
"whatsapp": {
"type": "http",
"url": "http://127.0.0.1:8765/mcp"
}
}
}Manual server start
MANUAL SERVER START · TERMINAL
./bin/whatsapp-mcp serve -addr 127.0.0.1:8765
