WhatsApp MCP by Very Good Plugins
An MCP server for personal WhatsApp: read and search chats, send text and files, react, send voice notes and transcribe them
- 284 ★ on the repository
- Last commit
Broad access
Why this level
- The agent reads all personal conversations, contacts and attachments and can send messages in your name
- The bridge acts as a linked device of your account and stores messages in a local database
- A configured webhook forwards messages and the bridge token to the selected service; MCP network transports require external authentication
Install
- Works in
Manual install
git clone https://github.com/verygoodplugins/whatsapp-mcp.git
cd whatsapp-mcp/whatsapp-bridge
go run .Starts the bridge; on first start it shows a QR code for WhatsApp and stores the bridge token in `whatsapp-bridge/store/.bridge-token`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads all personal conversations, contacts and attachments and can send messages in your name
- The bridge acts as a linked device of your account and stores messages in a local database
- A configured webhook forwards messages and the bridge token to the selected service; MCP network transports require external authentication
This is third-party code. Review the repository files before installing.
What it does
The Very Good Plugins fork of WhatsApp MCP connects Claude or Cursor to your personal WhatsApp account. The work is split in two. A Go bridge attaches to WhatsApp as a linked device, shows a QR code for sign-in and stores available conversation history in a local SQLite database. A Python MCP server reads that database and sends messages through the bridge. Tool results enter the agent’s context. The server has tools for contacts (`search_contacts`, `get_contact`), chats (`list_chats`, `get_chat`, `get_direct_chat_by_contact`, `get_contact_chats`, `get_last_interaction`) and messages (`list_messages`, `get_message_context`). Sending covers text with quoting and mentions (`send_message`), files (`send_file`), voice notes (`send_audio_message`) and reactions (`send_reaction`). Read receipts go out only on the explicit `mark_messages_read` command. Incoming media downloads through `download_media`, and `view_media` returns an image or the first frame of a video straight into the chat for clients without file access. `transcribe_audio` transcribes voice notes locally through whisper.cpp or through a compatible endpoint and stores the text in the message. Calls land in a local table, and incoming messages can be forwarded by webhook.
Who it is for. For people who want to work through their own WhatsApp conversations and reply to messages through Claude Desktop or Cursor and are ready to build a Go bridge.
Good fit when
- You need to find an agreement, a figure or a file in a long conversation and get the messages around it
- You want to compose and send a reply to a personal chat or a group, including a quoted reply with a mention
- Voice notes have piled up and must be transcribed locally without sending audio out
- Incoming messages should be forwarded by webhook into your system at `WEBHOOK_URL`
- You need to download attachments and view chat images in a client with no filesystem access
Not a fit when
- You need the official WhatsApp business channel with templates and company verification: the server treats a regular personal account as a device
- You are not ready to keep the Go bridge running: the server cannot receive or send messages without it
- The machine lacks Go 1.26, Python 3.11 and the `uv` manager: the build will not work
- You want bulk messaging to a contact list: the server is built for personal conversations with an agent
Example request
Find the latest message about the contract in the chat with Alex, show five messages before and after it, then draft a reply but do not send it without my confirmationMCP
- Transport
- stdio, http, sse
- Authentication
- not required
Environment variables
WHATSAPP_BRIDGE_TOKENsecret- Bearer token for bridge requests, read by default from a file next to the database.
WEBHOOK_URL- Address that receives forwarded incoming messages.
WEBHOOK_ENABLED- The value false disables outbound webhooks.
WHATSAPP_MEDIA_ROOTS- Directories from which sending files is allowed.
WHISPER_MODEL- Path to the model for whisper.cpp transcription.
Limitations
Go 1.26, Python 3.11 or later and `uv` are required. Run the bridge and MCP server from a shared checkout and link WhatsApp with a QR code. Local transcription needs whisper.cpp, a model and FFmpeg. An external transcription service receives the original audio.
Local SQLite history is not encrypted merely because WhatsApp encrypts messages in transit. Retrieved conversations reach the agent’s model. The bridge REST interface requires a token, but MCP network transports lack built-in authentication; the main installation path uses stdio.
Webhook forwarding defaults to a local address. If setting `WEBHOOK_URL`, use a trusted service: it receives the bridge token alongside messages. The server has no separate approval step for sending messages. The code uses MIT.
How to disable. Stop the Go bridge and remove the whatsapp block from the Claude Desktop or Cursor config. To unlink the device, open the linked devices list in the WhatsApp app and remove it. Local databases live in the `whatsapp-bridge/store/` folder.
FAQ
How do I connect WhatsApp MCP to Claude Desktop?
Clone the repository, run `go run .` in the `whatsapp-bridge` folder and scan the QR code in WhatsApp. Then add a server to `claude_desktop_config.json` with the `uv` command and the arguments `--directory`, the absolute path to `whatsapp-mcp-server`, `run`, `main.py`, and restart Claude Desktop.
Where is my chat history stored and what does Claude get?
History received by the bridge is stored in SQLite on your machine. MCP returns selected messages to the client, which may pass them to a model. Webhooks and external transcription add further data paths; check their settings separately.
Do I need to re-link the device after updating?
Usually restarting both components after an update is sufficient; the session and history remain in store. Relinking may be needed if WhatsApp revoked the device or you request full history. MCP must read the current bridge token.
How are voice notes transcribed?
`transcribe_audio` runs whisper.cpp on your machine by default: it needs `whisper-cli` on PATH, FFmpeg and a model in `WHISPER_MODEL`. You can point it to a compatible endpoint with `WHATSAPP_TRANSCRIPTION_URL`, and then the audio goes there. The transcript carries a prefix so it cannot be mistaken for human text.
Can I expose the server over the network?
Yes, with `WHATSAPP_MCP_TRANSPORT=http` (endpoint `/mcp`) or `sse`. The default host is `127.0.0.1` and the server has no built-in authentication, so bind it to an external address only behind an authenticating proxy or tunnel.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server for your personal WhatsApp account: search and read chats, contacts, send messages and files through an agent
An MCP server searches and reads owned WhatsApp history as a linked device so agents can find messages and prepare summaries.
Telegram MCP by chaindead
Telegram MCP
A Go MCP server for your Telegram account: the agent reads dialogs and unread messages, marks them read, leaves replies as drafts
An MCP server for macOS: an agent reads, searches and sends messages in the Messages app on your Mac
A Go utility with JSON output: an agent reads WhatsApp chats, searches messages and contacts and sends texts from your number
A Telethon MCP server: the agent reads and sends messages and manages chats, contacts and folders in your Telegram account
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| WhatsApp MCP by Very Good Plugins (this card) | no | not required | 284 | |
| WhatsApp MCP Server | no | not required | 6,816 | Luke Harries’s original project for reading and sending messages; the VGP fork adds audio transcription, media viewing and reactions |
| SendPulse MCP server for WhatsApp and SMS | no | API key | 2 | WhatsApp bots and SMS through SendPulse, with no personal account connected |
README in short
The fork keeps Luke Harries’s original Go-bridge and Python-server structure. Very Good Plugins adds reactions, explicit read receipts and media viewing for clients without filesystem access.