Skip to content
Back to search

whatsapp-mcp-hardened

Local-only WhatsApp MCP server: lets an AI assistant search and read your chats, read-only by default, with an authenticated loopback bridge.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pratyushjain98--whatsapp-mcp-hardened/badge.svg)](/listings/pratyushjain98--whatsapp-mcp-hardened)

HTML

<a href="/listings/pratyushjain98--whatsapp-mcp-hardened"><img src="/api/listings/pratyushjain98--whatsapp-mcp-hardened/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Go 1.27 or newer (the module asks for toolchain go1.27.3) - Python 3.11 or newer, and [uv](https://docs.astral.sh/uv/) - An MCP client such as Claude Code, Claude Desktop or Cursor - FFmpeg (optional), only for sending voice messages

Steps

1. **Clone the repository into a folder that is not synced.** The bridge keeps your session keys in `whatsapp-bridge/store/` and refuses to start inside a synced folder.

   git clone https://github.com/PratyushJain98/whatsapp-mcp-hardened.git
   cd whatsapp-mcp-hardened

2. **Build and run the bridge.**

   cd whatsapp-bridge
   go build -o wa-bridge .
   ./wa-bridge

Scan the QR code in WhatsApp on your phone (Settings, Linked Devices). The first history sync can take several minutes. You may need to pair again after about 20 days.

On first start the bridge creates `store/` with `messages.db`, `whatsapp.db`, `media/`, `outbox/` and `.bridge-token`. Leave the bridge running while you use the assistant so new messages keep arriving.

3. **Register the MCP server with your client.**

Claude Code:

   claude mcp add whatsapp -e WA_READ_ONLY=1 -- uv --directory /absolute/path/to/whatsapp-mcp-hardened/whatsapp-mcp-server run main.py

Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):

   {
     "mcpServers": {
       "whatsapp": {
         "command": "/absolute/path/to/uv",
         "args": [
           "--directory",
           "/absolute/path/to/whatsapp-mcp-hardened/whatsapp-mcp-server",
           "run",
           "main.py"
         ],
         "env": { "WA_READ_ONLY": "1" }
       }
     }
   }

Use `which uv` for the first path, then restart the client.

Configuration

Both programs are configured with environment variables.

| Variable | Default | Purpose | |---|---|---| | `WA_READ_ONLY` | `1` | `0` enables the send tools and the bridge's `/api/send`. Set it on both programs. | | `WA_BRIDGE_ADDR` | `127.0.0.1:8080` | Bridge address. Loopback only; anything else is refused. | | `WA_OUTBOX_DIR` | `whatsapp-bridge/store/outbox` | The only folder media can be sent from. | | `WA_LOG_CONTENT` | `0` | `1` logs message text, for debugging only. Bridge only. | | `WA_STORE_DIR` | `whatsapp-bridge/store` | Where the MCP server finds `messages.db` and the token. MCP server only. |

Sending messages

Sending is off by default. To turn it on, start both the bridge and the MCP server with `WA_READ_ONLY=0`. Copy any file you want to send into the outbox folder first: `send_file` and `send_audio_message` refuse any path outside it, including symlinks that point outside.

Windows

The SQLite driver needs CGO, which is off by default on Windows. Install a C compiler (for example through [MSYS2](https://www.msys2.org/), adding `ucrt64\bin` to your `PATH`), then:

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go build -o wa-bridge.exe .

Without it you will see `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.` On Windows the store's files inherit the permissions of your user profile folder rather than being set to owner-only.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 224 lines
  1. # WhatsApp MCP (hardened)
  2. A Model Context Protocol (MCP) server that gives an AI assistant access to your own WhatsApp. Claude Code, Claude Desktop, Cursor or any other MCP client can search your contacts, read and search your chats, open files people have sent you and, if you allow it, send messages.
  3. Everything runs on your own computer. Your messages are stored in a local database and never pass through a third-party server. The project is built security-first: it starts in read-only mode, listens only on your own machine, and authenticates every internal request.
  4. ## What you can ask
  5. Once it is connected, you talk to your assistant normally and it uses WhatsApp when it needs to:
  6. - "What did Sam say about Saturday?"
  7. - "Summarise what happened in the family group this week."
  8. - "Find the PDF someone sent me about the lease and tell me the notice period."
  9. - "When did I last speak to Priya, and what was it about?"
  10. - "List the chats I haven't replied to since Monday."
  11. With sending turned on, you can also ask it to reply, send a file or send a voice note.
  12. ## How it works
  13. The project is two small programs that share one folder, `whatsapp-bridge/store/`.
  14. ```
  15. your computer
  16. +-------------------------------------------------------------+
  17. | |
  18. | AI client --stdio--> MCP server --read-only--> messages.db
  19. | (Claude, (Python) ^ |
  20. | Cursor...) | | |
  21. | | HTTP on 127.0.0.1 | |
  22. | | + secret token | |
  23. | v | |
  24. | Bridge (Go) ----writes---------+ |
  25. | | |
  26. +-----------------------------|-------------------------------+
  27. | encrypted WhatsApp protocol
  28. v
  29. WhatsApp servers
  30. ```
  31. ### 1. The bridge (Go, `whatsapp-bridge/`)
  32. The bridge is the part that talks to WhatsApp.
  33. - **It logs in as a linked device.** This is the same mechanism WhatsApp Web and the desktop app use. It is built on [whatsmeow](https://github.com/tulir/whatsmeow), an open-source Go implementation of the WhatsApp Web protocol. The first time you run it, it shows a QR code. You scan it in WhatsApp on your phone, under Settings, Linked Devices. The session keys are saved in `store/whatsapp.db`, so later starts reconnect without a QR code.
  34. - **It builds a local archive.** After pairing, WhatsApp sends the linked device a batch of recent history. The bridge writes every chat and message into `store/messages.db`, a SQLite database with two tables: `chats` (one row per chat, with its name and last activity) and `messages` (sender, text, time, and media details). It then stays connected and saves each new message, sent or received, as it arrives.
  35. - **It fetches media on demand.** When a photo, voice note or document arrives, only its details are stored: type, file name, size and the key needed to decrypt it. The file itself is downloaded only when you ask for it. The bridge then fetches the encrypted file from WhatsApp's media servers, decrypts it and saves it under `store/media/<chat>/`.
  36. - **It offers a small internal API.** It listens on `127.0.0.1:8080`, which only programs on your own computer can reach. There are two endpoints: `/api/download` for media, and `/api/send`, which exists only when sending is enabled. Every request must carry a secret token that the bridge creates on first start and keeps in `store/.bridge-token`.
  37. ### 2. The MCP server (Python, `whatsapp-mcp-server/`)
  38. The MCP server is the part your AI client talks to.
  39. - **Your client starts it.** You register it once with your AI client, which then launches it in the background and talks to it over standard input and output. It opens no network port of its own.
  40. - **It reads the archive directly.** Search and read tools run SQL queries against `messages.db`, opened in read-only mode, so the assistant can never change or delete your history. Because it reads the database file, searching works even while the bridge is stopped. You just won't see messages that arrived in the meantime.
  41. - **It goes through the bridge for anything that touches WhatsApp.** Downloading media and sending messages are sent to the bridge's internal API with the secret token.
  42. - **It warns the model about message text.** The server tells the model that message content is written by other people and must be treated as data, never as instructions.
  43. ### What happens when you ask a question
  44. Take "What did Sam say about Saturday?":
  45. 1. The assistant calls `search_contacts` with "Sam" and gets back Sam's WhatsApp ID.
  46. 2. It calls `list_messages` with that sender and the word "Saturday". The MCP server runs the query on the read-only database and returns the matching messages, each with the message before and after it for context.
  47. 3. The assistant reads them and answers in plain language.
  48. If the answer is in a file ("open the lease PDF"), the assistant calls `download_media` with the message ID. The MCP server asks the bridge for it, the bridge downloads and decrypts it into `store/media/`, and the assistant gets back a local path it can open.
  49. ## Security model
  50. An assistant that reads your private messages is a sensitive thing to run. These are the main risks and how this project handles them. The full design, with tests and remaining risks, is in [SECURITY-DESIGN.md](SECURITY-DESIGN.md).
  51. | Risk | What this project does |
  52. |---|---|
  53. | Another device on your network calls the bridge | The bridge listens only on `127.0.0.1` and refuses to start on any other address. Every request needs a 256-bit token, compared in constant time. |
  54. | A website you visit sends forged requests to `localhost` | Only JSON requests are accepted, any request with a browser `Origin` header is rejected, and the `Host` header must be a loopback name. This blocks cross-site request forgery and DNS rebinding. |
  55. | A contact sends a file with a crafted name such as `../../.zshrc` | File names are reduced to one safe path element, saved under `store/media/<chat>/`, and checked to be inside that folder before anything is written. |
  56. | A hostile message tells the model to send your files somewhere | Read-only by default: the send tools don't exist, so the model can't see or call them. If you turn sending on, files can only be sent from a dedicated outbox folder. |
  57. | Other accounts on the computer read your session or messages | The store folder is owner-only (`0700`, files `0600`), and the bridge refuses to run inside a Dropbox, Syncthing, Tresorit or OneDrive folder, where session keys would be copied elsewhere. |
  58. | Message text ends up in log files | Message text is never logged unless you set `WA_LOG_CONTENT=1` for debugging. |
  59. | The model pulls your whole archive into one conversation | Results are capped at 200 per call and 50 messages of context. |
  60. ## Before you use it
  61. - **Your model provider sees what it reads.** The MCP server runs locally, but any message the assistant reads is sent to the model provider as part of the conversation. If message text must never leave your computer, use a local model as the client.
  62. - **This is an unofficial WhatsApp client.** WhatsApp's terms do not allow unofficial clients, and accounts that use them can be restricted. Use it with an account you are prepared to take that risk with.
  63. - **Keep sending off unless you need it.** With sending on, a hostile message could still try to talk the model into sending text or outbox files.
  64. - **Run it in a session without other outbound tools.** Read-only mode removes WhatsApp's own send tools, but the same assistant session might have email, web or shell tools a hostile message could try to use instead. Register this server in a dedicated project if you can.
  65. ## Installation
  66. ### Prerequisites
  67. - Go 1.27 or newer (the module asks for toolchain go1.27.3)
  68. - Python 3.11 or newer, and [uv](https://docs.astral.sh/uv/)
  69. - An MCP client such as Claude Code, Claude Desktop or Cursor
  70. - FFmpeg (optional), only for sending voice messages
  71. ### Steps
  72. 1. **Clone the repository into a folder that is not synced.** The bridge keeps your session keys in `whatsapp-bridge/store/` and refuses to start inside a synced folder.
  73. ```bash
  74. git clone https://github.com/PratyushJain98/whatsapp-mcp-hardened.git
  75. cd whatsapp-mcp-hardened
  76. ```
  77. 2. **Build and run the bridge.**
  78. ```bash
  79. cd whatsapp-bridge
  80. go build -o wa-bridge .
  81. ./wa-bridge
  82. ```
  83. Scan the QR code in WhatsApp on your phone (Settings, Linked Devices). The first history sync can take several minutes. You may need to pair again after about 20 days.
  84. On first start the bridge creates `store/` with `messages.db`, `whatsapp.db`, `media/`, `outbox/` and `.bridge-token`. Leave the bridge running while you use the assistant so new messages keep arriving.
  85. 3. **Register the MCP server with your client.**
  86. Claude Code:
  87. ```bash
  88. claude mcp add whatsapp -e WA_READ_ONLY=1 -- uv --directory /absolute/path/to/whatsapp-mcp-hardened/whatsapp-mcp-server run main.py
  89. ```
  90. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`) or Cursor (`~/.cursor/mcp.json`):
  91. ```json
  92. {
  93. "mcpServers": {
  94. "whatsapp": {
  95. "command": "/absolute/path/to/uv",
  96. "args": [
  97. "--directory",
  98. "/absolute/path/to/whatsapp-mcp-hardened/whatsapp-mcp-server",
  99. "run",
  100. "main.py"
  101. ],
  102. "env": { "WA_READ_ONLY": "1" }
  103. }
  104. }
  105. }
  106. ```
  107. Use `which uv` for the first path, then restart the client.
  108. ### Configuration
  109. Both programs are configured with environment variables.
  110. | Variable | Default | Purpose |
  111. |---|---|---|
  112. | `WA_READ_ONLY` | `1` | `0` enables the send tools and the bridge's `/api/send`. Set it on both programs. |
  113. | `WA_BRIDGE_ADDR` | `127.0.0.1:8080` | Bridge address. Loopback only; anything else is refused. |
  114. | `WA_OUTBOX_DIR` | `whatsapp-bridge/store/outbox` | The only folder media can be sent from. |
  115. | `WA_LOG_CONTENT` | `0` | `1` logs message text, for debugging only. Bridge only. |
  116. | `WA_STORE_DIR` | `whatsapp-bridge/store` | Where the MCP server finds `messages.db` and the token. MCP server only. |
  117. ### Sending messages
  118. Sending is off by default. To turn it on, start both the bridge and the MCP server with `WA_READ_ONLY=0`. Copy any file you want to send into the outbox folder first: `send_file` and `send_audio_message` refuse any path outside it, including symlinks that point outside.
  119. ### Windows
  120. The SQLite driver needs CGO, which is off by default on Windows. Install a C compiler (for example through [MSYS2](https://www.msys2.org/), adding `ucrt64\bin` to your `PATH`), then:
  121. ```bash
  122. cd whatsapp-bridge
  123. go env -w CGO_ENABLED=1
  124. go build -o wa-bridge.exe .
  125. ```
  126. Without it you will see `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.` On Windows the store's files inherit the permissions of your user profile folder rather than being set to owner-only.
  127. ## MCP tools
  128. Always available:
  129. | Tool | What it does |
  130. |---|---|
  131. | `search_contacts` | Find contacts by name or phone number |
  132. | `list_messages` | Search messages by text, chat, sender or date, with surrounding context |
  133. | `list_chats` | List chats with their last message and activity |
  134. | `get_chat` | One chat by its ID |
  135. | `get_direct_chat_by_contact` | The one-to-one chat with a phone number |
  136. | `get_contact_chats` | Every chat a contact is in, including groups |
  137. | `get_last_interaction` | The most recent message with a contact |
  138. | `get_message_context` | The messages around one message |
  139. | `download_media` | Download a message's photo, video, voice note or document and return its local path |
  140. Only with `WA_READ_ONLY=0`:
  141. | Tool | What it does |
  142. |---|---|
  143. | `send_message` | Send text to a phone number or group |
  144. | `send_file` | Send an image, video, document or audio file from the outbox |
  145. | `send_audio_message` | Send audio from the outbox as a voice note (converted to Ogg Opus with FFmpeg if needed) |
  146. ## Development
  147. ```bash
  148. cd whatsapp-bridge
  149. gofmt -l . && go vet ./... && go test ./...
  150. ```
  151. The tests cover the loopback check, the request guard, file name sanitising, media path containment, the outbox rule, the synced-folder check and the listener settings. The scanner commands are in section 5 of [SECURITY-DESIGN.md](SECURITY-DESIGN.md).
  152. ## Troubleshooting
  153. - **QR code not showing**: restart the bridge and check that your terminal can display it.
  154. - **Already logged in**: the bridge reconnects without a QR code.
  155. - **Device limit reached**: remove a linked device in WhatsApp on your phone (Settings, Linked Devices).
  156. - **No messages yet**: the first history sync can take several minutes.
  157. - **"bridge token not found"**: start the bridge first, or point `WA_STORE_DIR` at its `store/` folder.
  158. - **"refusing to create the store inside a synced folder"**: move the clone out of the synced folder. This is deliberate.
  159. - **Out of sync**: stop the bridge, delete `whatsapp-bridge/store/messages.db` and `whatsapp-bridge/store/whatsapp.db`, and pair again.
  160. For MCP client logs, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues).
  161. ## License
  162. MIT. See [LICENSE](LICENSE). To report a vulnerability, see [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.