WhatsAppCAUTION
WhatsApp MCP server - Connect Claude to WhatsApp for reading and sending messages
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
[](https://github.com/verygoodplugins/whatsapp-mcp/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://go.dev/)
A Model Context Protocol (MCP) server for WhatsApp, enabling Claude to read and send WhatsApp messages.
Originally created by Luke Harries. Maintained by Very Good Plugins.
Watch the WhatsApp MCP demo video
Product demo generated with Remotion using simulated data.
Features
- Message Management: Search and read personal WhatsApp messages (text, images, videos, documents, audio)
- Contact Search: Search contacts by name or phone number with
sender_displayformat ("Name (phone)") - Send Messages: Send text messages to individuals or groups
- Read Receipts: Explicitly mark selected messages as read across linked devices
- Media Support: Send and download images, videos, documents, and voice messages
- Call History: Capture incoming voice/video calls into a local SQLite table (live, 1:1 and group)
- Webhook Integration: Forward incoming messages to external services
- Local Storage: All messages stored locally in SQLite - only sent to Claude when you allow it
Installation
Prerequisites
- Go 1.26+
- Python 3.11+
- uv package manager
- Claude Desktop or Cursor
- FFmpeg (optional, for voice message conversion)
Quick Start
- **Clone the repository
a2677d122a03OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add whatsapp-mcp-server -- None whatsapp-mcp-server==0.7.0
Exposed tools (17)
12 read · 4 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
download_media | read | Download media from a WhatsApp message and get the local file path. |
get_chat | read | Get WhatsApp chat metadata by JID. |
get_contact | read | Look up a WhatsApp contact by phone number, LID, or full JID. |
get_contact_chats | read | Get all WhatsApp chats involving the contact. |
get_direct_chat_by_contact | read | Get WhatsApp chat metadata by sender phone number. |
get_last_interaction | read | Get most recent WhatsApp message involving the contact. |
get_message_context | read | Get context around a specific WhatsApp message. |
list_chats | read | Get WhatsApp chats matching specified criteria. |
list_messages | read | Get WhatsApp messages matching specified criteria with optional context. |
mark_messages_read | write | Mark selected WhatsApp messages as read and send read receipts. |
search_contacts | read | Search WhatsApp contacts by name or phone number. |
send_audio_message | write | Send any audio file as a WhatsApp audio message to the specified recipient. For group messages use the JID. If it errors due to ffmpeg not being installed, use send_file instead. |
send_file | write | Send a file (image, video, document) via WhatsApp, optionally with a caption. |
send_message | write | Send a WhatsApp message to a person or group. For group chats use the JID. |
send_reaction | destructive | Send (or remove) a reaction to a WhatsApp message. |
transcribe_audio | read | Transcribe a WhatsApp voice note and return its text. |
view_media | read | View the media of a WhatsApp message as an image. |
Trust audit
CAUTIONgrade C · trust 71/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (5 observation(s))
- Shell
- none-observed
- Dependencies
- pinned
- Secrets in source
- found
Findings (21)
# WHATSAPP_TRANSCRIPTION_URL=http://127.0.0.1:8178/v1/audio/transcriptions
API_URL="${WHATSAPP_API_URL:-http://127.0.0.1:${PORT}/api}"const token = "abcd1234abcd1234abcd1234abcd1234"
const token = "supersecrettoken1234567890abcdef"
const token = "supersecrettoken1234567890abcdef"
const token = "supersecrettoken1234567890abcdef"
const token = "supersecrettoken1234567890abcdef"
send_reaction
.release-please-manifest.json
.golangci.yml
target := writeFile(t, secrets, "id_rsa", "PRETEND-PRIVATE-KEY")
{name: "message nested traversal", chatJID: "[email protected]", messageID: "nested/../../outside"},WHATSAPP_TRANSCRIPTION_URL=http://127.0.0.1:8178/v1/audio/transcriptions
curl -X POST http://127.0.0.1:8080/api/history \
`http://127.0.0.1:<port>/api`, `http://localhost:<port>/api`, or
assert base64.b64decode(image.to_image_content().data) == b"image-bytes"
png_bytes = base64.b64decode(
assert base64.b64decode(content.data) == png_bytes
so the MCP server can read the bridge token. If the two components do not share
example-use.png
- [@maikol-solis](https://github.com/maikol-solis) — bridge run command fix (#23)
Gates applied: no_behavioural_pass.
a2677d122a03full audit observations/trust-audit/mcp-server/verygoodplugins__whatsapp-20.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | a2677d122a03 | CAUTION | C | 71 | first audit |
Questions
What is the WhatsApp MCP server?
WhatsApp MCP server - Connect Claude to WhatsApp for reading and sending messages
What tools does WhatsApp expose?
17 in total: 12 read-only, 4 that write, and 1 that can delete or overwrite (send_reaction). Every one is listed on this page with its risk.
Is WhatsApp safe to connect to an agent?
With care. The audit graded it C (71/100) and found 21 things worth knowing before you trust this server, listed below with the exact line each was found on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does WhatsApp need?
It reads WHATSAPP_BRIDGE_TOKEN and WHATSAPP_TRANSCRIPTION_API_KEY from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does WhatsApp run?
It speaks stdio and streamable-http, so it runs as a local process your client starts. It is published on PyPI as whatsapp-mcp-server.
How current is this page?
The grade is for one exact copy of the source (a2677d122a03), read on 2026-10-07. The repository is watched and re-audited when it changes.