Links a personal WhatsApp account as a companion device (via pairing code) and keeps a local archive of the account's messages. Provides tools to search contacts and chats, list and full-text search messages with optional surrounding context, retrieve the latest interaction with someone or every chat a contact appears in, download media attachments (images, video, audio, documents, stickers), and send messages, files or audio messages — sends are previewed first and only go through when confirmed. Also handles linking and unlinking the computer and optionally deleting the stored archive.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@askmywa search my WhatsApp chats for the restaurant recommendation from Marco"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
askmywa.com · Version française · Privacy policy
An MCP server for your personal WhatsApp account, as a single Go binary for Mac, Windows and Linux, including Raspberry Pi.
It links to WhatsApp as a companion device through whatsmeow, keeps a local archive of your messages, and lets an assistant such as Claude Desktop search them, read them, download attachments and, after your approval, send messages and files.
Local archive. Every message lands in a SQLite database on your computer. Nothing reaches the assistant unless it calls a tool.
Real names. Senders are resolved when messages are stored, from your address book first, then the name people set for themselves. Phone numbers and WhatsApp's hidden @lid identifiers are merged into one contact.
Full-text search. Accent- and case-insensitive: ecole finds école.
Typed tools. Every tool declares its input and output schema, paginates with a cursor and returns errors that say how to fix the call.
Sending needs your approval. send_message, send_file and send_audio_message only return a preview (recipient, resolved name, group or not, content). They send only when called again with confirm=true.
No network port. The MCP server talks to the WhatsApp daemon over a private Unix socket. Files can only be sent from one configured folder.
Caution. Like any MCP server that reads private data and can send messages, this one is exposed to the lethal trifecta: a prompt injection hidden in a message could try to make the assistant leak data. The confirmation step on every send is the main safeguard, so read previews before approving them.
Related MCP server: whatsapp-mcp-local
This is a rewrite, not a patch set. The tool names and the WhatsApp library are the same, so assistants and prompts written for the original keep working.
This project | ||
Components | Go bridge plus a Python MCP server run with | One Go binary |
Link between them | HTTP API on port 8080 of every network interface, no authentication | Private Unix socket, readable only by you |
Sender names | Looked up at read time from the chat list; group members and | Resolved when stored, from the address book first; phone numbers and |
Search |
| SQLite FTS5 index, accent- and case-insensitive |
Tool results | Mostly formatted text, page numbers | Typed JSON with schemas, cursor pagination with |
Sending | Immediate | Preview first, sent only with |
Files that can be sent | Any readable path | Only files under one configured folder |
Running it |
| A background service with rotated logs on Mac, Windows and Linux |
Installing it | Go, Python, | A Claude Desktop extension, linked with a code typed on the phone |
An existing install of the original can switch without pairing again: the new daemon copies the old session and imports the old history, and never writes to the old files. See Migrating from the original project.
Download askmywa.mcpb, the latest version, from askmywa.com or the releases. The same file works on Mac and Windows.
Double-click it. Claude Desktop opens and asks you to confirm the install.
In a new conversation, write: Connect my WhatsApp. The first time, Claude asks for permission to use askmywa's tools: choose to always allow them, so it doesn't ask again. Sending stays safe either way: every message waits for your yes.
Claude asks for your phone number, then gives you an 8-character code. On your phone, open WhatsApp > Settings (on Android, the ⋮ menu) > Linked devices > Link a device > Link with phone number instead, and type the code.
That's it. Your messages start appearing within a few minutes, and the link keeps working after a restart. To send a file, put it in the Documents/WhatsApp MCP folder first (you can choose another folder in the extension's settings).
To remove it, ask Claude to disconnect WhatsApp from this computer (it unlinks the computer, stops the background service and, if you want, deletes the stored messages), then uninstall the extension in Claude Desktop's settings.
The Mac app is signed and notarized by Apple. The Windows app is not code-signed yet: if Windows shows a SmartScreen warning, choose More info > Run anyway.
It talks to WhatsApp through an unofficial interface, the same way WhatsApp Web automation tools do. WhatsApp's terms do not allow this, and WhatsApp could restrict an account that uses it.
On Linux, a Raspberry Pi or a Mac, one command downloads the right build, checks its SHA-256, installs it (on a Mac, askmywa.app in ~/Applications, with the command linked in ~/.local/bin), starts the background service and offers to link WhatsApp:
curl -fsSL https://github.com/Ruwad-io/askmywa/releases/latest/download/install.sh | shRun it again to upgrade. Add sh -s -- --no-service after the pipe to install only the binary. If the ChatGPT desktop app or Codex is set up for your user (~/.codex), the installer also adds askmywa to their MCP servers; quit and reopen ChatGPT to use it, or pass --no-codex to skip this.
With Homebrew on Mac or Linux:
brew install ruwad-io/tap/askmywa
askmywa install-service
askmywa linkOr download the archive for your system from the latest release:
System | Archive |
Mac (Apple Silicon / Intel) |
|
Windows (x64 / ARM) |
|
Linux, Raspberry Pi 3, 4 and 5 |
|
Raspberry Pi with a 32-bit kernel (Pi 2, older Pi OS) |
|
You can also build from source with Go 1.26 or newer:
git clone https://github.com/Ruwad-io/askmywa.git
cd askmywa/whatsapp-go
mkdir -p ~/.local/bin
go build -o ~/.local/bin/askmywa .After a manual download or a build, install the background service, which starts at login (a launchd agent on Mac, a systemd user service on Linux, a scheduled task on Windows), then link WhatsApp:
~/.local/bin/askmywa install-service
~/.local/bin/askmywa linklink asks for your phone number and prints an 8-character code. On your phone, open WhatsApp > Settings (on Android, the ⋮ menu) > Linked devices > Link a device > Link with phone number instead, and type the code. You can also ask Claude to connect WhatsApp instead.
Add the server to Claude Desktop's claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart Claude Desktop. The path must be absolute: ~ is not expanded there.
{
"mcpServers": {
"whatsapp": {
"command": "/Users/YOU/.local/bin/askmywa",
"args": ["serve"]
}
}
}On Windows, use the full path to askmywa.exe, with doubled backslashes. Cursor uses the same block in ~/.cursor/mcp.json, and Claude Code accepts it with claude mcp add whatsapp -- /path/to/askmywa serve. For Codex and the ChatGPT desktop app, which share ~/.codex/config.toml: codex mcp add askmywa -- /path/to/askmywa serve.
A Pi left on keeps the archive complete even when your laptop sleeps. Connect to the Pi over SSH and run the one-line installer above: it installs the service, asks systemd to keep it running after you log out, and links WhatsApp with a code typed on your phone, so no QR code or screen is needed.
Claude Desktop on your laptop can then use the Pi over SSH, provided you log in to the Pi with an SSH key, without a password prompt:
{
"mcpServers": {
"whatsapp": {
"command": "ssh",
"args": ["pi@raspberrypi.local", "/home/pi/.local/bin/askmywa", "serve"]
}
}
}Files to send must then be on the Pi, in its send folder.
Tool | What it does |
| Whether WhatsApp is set up and connected, and what to do next |
| Start the background service and link this computer with a pairing code |
| Unlink this computer, stop the service and optionally delete the archive, after a preview |
| Find people by name or number |
| Chats, most recent first or by name |
| Messages filtered by chat, sender, dates and full-text query, with optional surrounding context |
| One chat, the direct chat with someone, every chat they appear in |
| Latest exchange with someone, messages around a given one |
| Save an image, video, audio, document or sticker and return its path |
| Preview by default, send with |
Contacts can be given as a phone number, a JID or a name.
whatsapp-go/README.md covers the data layout, migration from the original project, service management, configuration and development.
Started as a fork of lharries/whatsapp-mcp by Luke Harries, MIT licensed. The voice-note encoding and the overall tool set come from that project; its Go bridge and Python server were removed once this binary replaced them, and remain in this repository's git history.
Set up WhatsApp on this computer: start the background service if needed and, when the computer is not linked yet, get an 8-character pairing code for the user's phone number. Only call this when the user asked to connect or set up WhatsApp, and ask them for the phone number of their own WhatsApp account first (international format, for example 33612345678). Show the code and the instructions to the user exactly as returned: they type the code on their phone, which is what links the account. WhatsApp also shows a notification on the phone. Calling it again while a code is valid returns the same code; when the computer is already linked it only reports the account.
Inputs: phone_number. Returns: code, state, account, expires_at, +1 more
Unlink this computer from WhatsApp (it disappears from Linked devices on the phone) and stop the background service; with delete_archive, also delete the stored messages, downloaded attachments and logs. Use it when the user wants to stop using WhatsApp here or before uninstalling the extension. Files in the send folder are never deleted.
Safety: with confirm=false (the default) NOTHING is changed; the tool returns the list of steps. Show it to the user and call again with confirm=true only after they approved. Never set confirm=true on the first call.
Inputs: confirm, delete_archive. Returns: done, steps, account, message, +1 more
Download the media (image, video, audio, document, sticker) attached to a message and return its local path. Use the id and chat_jid of a list_messages result whose media_type is set.
Inputs: chat_jid (required), message_id (required). Returns: path, size, cached, filename, +1 more
Get one chat by JID, with its latest message.
Inputs: chat_jid (required), include_last_message. Returns: jid, name, is_group, last_message, +1 more
List every chat involving a contact: the direct chat and the groups they wrote in, most recently active first. Paginated by cursor.
Inputs: contact (required), limit, cursor. Returns: chats, has_more, next_cursor
Get the one-to-one chat with a contact given their phone number, JID or name.
Inputs: contact (required). Returns: jid, name, is_group, last_message, +1 more
Get the most recent message exchanged with a contact (sent by them anywhere, or in their direct chat).
Inputs: contact (required). Returns: found, message
Get the messages before and after a given message in its chat.
Inputs: message_id (required), after, before, chat_jid. Returns: after, before, message
List WhatsApp chats (people and groups), most recently active first or by name, optionally filtered by a name, JID or contact. Paginated by cursor.
Inputs: limit, query, cursor, sort_by, +1 more. Returns: chats, has_more, next_cursor
List stored WhatsApp messages, newest first, optionally filtered by chat, sender, date range and a full-text query (words matched by prefix, accent- and case-insensitive). Results are paginated: pass next_cursor back as cursor while has_more is true. Set include_context to get the neighbouring messages of each hit.
Inputs: after, limit, query, before, +6 more. Returns: has_more, messages, next_cursor
Search WhatsApp contacts by name or phone number. Matching is case- and accent-insensitive ("elodie" finds "Élodie"). Each result gives the best known name, the phone number and/or LID, and the JID to pass to list_messages (chat_jid) or to the send tools (recipient).
Inputs: query (required), limit, cursor. Returns: contacts, has_more, next_cursor
Send an audio file as a WhatsApp voice note (converted to Opus with ffmpeg when needed; if ffmpeg is missing use send_file instead). The file must be under the daemon's send root directory.
Safety: with confirm=false (the default) NOTHING is sent; the tool returns a preview. Show it to the user and call again with confirm=true only after they approved. Never set confirm=true on the first call.
Inputs: recipient (required), media_path (required), confirm. Returns: sent, message, preview, timestamp, +2 more
Send a file (image, video, document, or an audio file as a plain attachment) with an optional caption. The file must be under the daemon's send root directory.
Safety: with confirm=false (the default) NOTHING is sent; the tool returns a preview. Show it to the user and call again with confirm=true only after they approved that exact file and recipient. Never set confirm=true on the first call.
Inputs: recipient (required), media_path (required), caption, confirm. Returns: sent, message, preview, timestamp, +2 more
Send a WhatsApp text message to a person or a group.
Safety: with confirm=false (the default) NOTHING is sent; the tool returns a preview (resolved recipient, their name, whether it is a group, the text). Show it to the user and call again with confirm=true only after they approved that exact content. Never set confirm=true on the first call. Recipient: phone number with country code and no plus sign, a JID (123@s.whatsapp.net, 123@g.us for a group) or a contact name.
Inputs: message (required), recipient (required), confirm. Returns: sent, message, preview, timestamp, +2 more
Report whether WhatsApp is set up on this computer: background service, link with the phone, connection, archive size, and the folder files can be sent from. next_step says in plain words what to do when something is missing. Call it first when another WhatsApp tool fails.
Returns: chats, linked, account, messages, +6 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
Most tools have clearly distinct purposes: sending, reading, searching, media, and account management are well separated. There is some potential overlap among get_chat, get_direct_chat_by_contact, get_contact_chats, list_chats, and get_last_interaction, but the descriptions make the distinctions reasonably clear.
Nearly all tools use consistent snake_case verb_noun naming such as list_messages, send_message, and search_contacts. The main minor deviation is whatsapp_status, which is noun_status rather than a verb-led action name, but the overall convention remains readable and predictable.
Fifteen tools is at the upper end of the recommended range but still well scoped for a WhatsApp integration. Each tool covers a distinct read, send, media, search, or account-management operation without obvious filler.
The surface covers core WhatsApp workflows well: setup/status, chats, messages, contacts, context, media download, and text/file/audio sending. Minor gaps remain around message management operations such as editing, deleting, reacting, or group administration, but agents can handle the main workflows.
Read, search and reply to your WhatsApp chats from your AI, using your own number.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Your own WhatsApp in Claude and ChatGPT: read chats, draft replies, send messages you approve.
Your WhatsApp history in Claude and ChatGPT: search years of chats, voice notes transcribed.
