whatsapp-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| WA_MCP_HOST | No | serve mode: where to listen. | 127.0.0.1 |
| WA_MCP_NAME | No | Name shown to clients and on the consent page. | |
| WA_MCP_PORT | No | serve mode: where to listen. | 3000 |
| WA_LOG_LEVEL | No | Baileys logging level for troubleshooting, e.g. info or debug. | silent |
| WA_PAIR_PHONE | No | Pair with an 8-character code instead of a QR code; phone number with country code. | |
| WA_PUBLIC_URL | No | serve mode: the public HTTPS URL, e.g. https://wa.example.com. | |
| WA_MCP_DATA_DIR | No | Session, message store and downloaded files. Use a second directory for a second account. | ~/.whatsapp-mcp |
| WA_MCP_PASSWORD | No | serve mode: the password on the OAuth consent page. Required for serve mode. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This is the user's WhatsApp account (read, search and send). It is a linked device, like WhatsApp Web.
How to use:
Find a person or group with search_contacts (name or phone number) or list_chats (most recent first, with unread counts). Both give the person's phone number when WhatsApp shares it.
Read a conversation with list_messages. It returns the newest messages; to go further back pass before = the time of the oldest message you got.
System events appear as text: "[system: disappearing messages turned on (7 days)]", "[deleted by sender]" (the original text is kept), "[edited]". Messages WhatsApp has not delivered yet say so; reading the chat asks the phone to send them again.
The stored history of a chat may start late. list_messages tells you history_complete. If it is false and you need older context, call load_full_history(chat): it asks the user's phone for older messages (the phone must be online) and can take up to two minutes. If it returns more_available, call it again. If history_complete is true but the user says older messages exist, call load_full_history with recheck: true (once).
search_messages finds text across all chats or inside one chat.
Messages with a file (image, video, voice note, document) have file: true and a message_id in list_messages; download_media(message_id) shows you the content (pictures, frames of a video, text of PDF/Word/Excel/CSV) and where the original is.
Reading never marks anything as read. mark_read(chat) does (blue ticks + clears the unread badge on the user's devices): use it only when the user asked, or their standing rule says so.
send_message sends a real WhatsApp message as the user. Only send what the user explicitly asked you to send, to the person they meant; when unsure who the recipient is, ask first.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_chatsA | List WhatsApp chats (people and groups), most recent first, with phone numbers and unread counts. unread_only: only chats with unread messages. |
| search_contactsA | Search contacts and chats by name or phone number; returns their phone numbers. |
| list_messagesA | Messages of one chat (jid, phone number, or contact/group name), oldest first. Returns the newest |
| search_messagesB | Full-text search in stored messages, across all chats or within one chat. |
| load_full_historyA | Fetch the older history of one chat from the user's phone (WhatsApp's history sync on demand), so the whole conversation becomes readable. The phone must be online; phones send roughly the last year. Can take up to two minutes; returns more_available when you should call it again. recheck: true asks again even for a chat marked complete. |
| download_mediaA | Download the file of a WhatsApp message (photo, video, voice note, sticker, document: PDF, Word, Excel, CSV, TXT…) and show its content: pictures as images, frames of a video, text of PDF/Word/Excel/CSV/TXT. Also returns where the original file is. message_id comes from list_messages (messages with file: true). |
| mark_readA | Mark a chat as read on the user's WhatsApp, like opening it on the phone: sends read receipts (blue ticks) and clears the unread badge on all their devices. Only when the user asked, or their standing rule says so. Reading with the other tools never marks anything read. |
| send_messageB | Send a WhatsApp text message as the user (recipient: jid, phone number with country code, or contact name). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
Each tool has a distinct primary action and resource: listing chats, searching contacts/messages, loading history, downloading media, marking read, and sending. Minor overlap exists between list_chats and search_contacts, since search_contacts also returns chats, but the descriptions make the intended use clear enough.
All tools follow a consistent snake_case verb_noun pattern (list_chats, search_messages, load_full_history, download_media, mark_read, send_message). There are no mixed conventions or vague standalone verbs.
Eight tools is well-scoped for a WhatsApp assistant covering discovery, reading, history loading, media handling, and sending. Each tool earns its place without redundant operations.
The surface covers core WhatsApp workflows: listing/searching chats and messages, loading older history, downloading media, marking read, and sending text. Minor gaps remain around sending media, replying/quoted messages, reactions, or group management, but core read/send workflows are covered.