Whatsapp

What whatsapp does

whatsapp exposes a linked WhatsApp account to MCP clients through wacli. Its core use cases are reading conversation data, searching messages, and sending messages. The underlying client also supports chat, contact, group, channel, media, profile, presence, and local-store operations, giving integrations access to more than a simple message relay.

wacli connects as a WhatsApp Web linked device using the whatsmeow protocol implementation. It is an independent client and is not affiliated with WhatsApp or Meta.

How it works

Pair the account by running the authentication flow and scanning the terminal QR code from WhatsApp’s Linked devices screen. The first authentication performs an initial sync. A follow mode can continue mirroring new events into local storage while the account remains connected.

The WhatsApp session database and the searchable message index are kept separately. Searches use the local index, allowing an agent to query synchronized messages without requiring an active WhatsApp connection at the moment of the search. History availability depends on what WhatsApp Web provides; the local history coverage can be inspected before attempting to retrieve older messages.

Recipients for outgoing messages may be phone numbers, WhatsApp JIDs, or names from synchronized contacts, groups, and chats. Sending is subject to the recipient being someone the account is allowed to contact.

Setup and configuration

Install a release archive for macOS, Linux, or Windows, use Homebrew on macOS or Linux, or build from source with Go 1.27.0 or newer and a C compiler. Official macOS binaries require macOS 15 or later. Source builds use the SQLite FTS5 build tag.

The default data directory is ~/.local/state/wacli on Linux and ~/.wacli on other platforms. Set WACLI_STORE_DIR or pass a store option to choose another location. Named accounts provide separate sessions, databases, and locks for multiple WhatsApp identities.

Set WACLI_READONLY=1, or use the equivalent read-only option, when an integration must not modify WhatsApp or the local store. JSON output is available for one-shot commands, while long-running commands can emit newline-delimited lifecycle events.

Tools and capabilities

• Read and inspect locally synchronized WhatsApp messages.
• Search messages, including searches filtered for media.
• Send text and files to phone numbers, JIDs, contacts, groups, or chats.
• Download synchronized media and export local records.
• Find contacts and inspect or change chat state, including read, archive, pin, and mute operations.
• Inspect groups, communities, channels, profile details, presence, storage, and diagnostics.

Limitations and notes

Search depends on the locally synchronized SQLite index, not on an unrestricted live search of WhatsApp. WhatsApp Web history is provided on a best-effort basis, so older conversations may not be available locally. Write operations use per-store locking; a running follow-mode sync process can coordinate supported send, chat-state, contact, and contact-save operations while it owns that lock.

Because the account is paired as a linked device, access depends on completing WhatsApp’s device-linking flow and maintaining the relevant local session. Read-only mode is available for integrations that should avoid changes.