Skip to content
Back to search

whatsapp-mcp

WhatsApp MCP server - Connect Claude to WhatsApp for reading and sending messages

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/verygoodplugins/whatsapp-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/verygoodplugins/whatsapp-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/verygoodplugins--whatsapp-mcp"><img src="/api/listings/verygoodplugins--whatsapp-mcp/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.26+ - Python 3.11+ - [uv](https://docs.astral.sh/uv/) package manager - Claude Desktop or Cursor - FFmpeg (optional, for voice message conversion)

Quick Start

1. **Clone the repository**

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

2. **Start the WhatsApp bridge**

   cd whatsapp-bridge
   go run .

On first start, the bridge prints and stores a local REST API token at `whatsapp-bridge/store/.bridge-token`. Scan the QR code with WhatsApp on your phone to authenticate.

3. **Configure Claude Desktop**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

Replace `/path/to/whatsapp-mcp` with your actual path.

4. **Restart Claude Desktop**

Updating

Pull the latest changes, then refresh whichever components moved:

git pull

| You changed | What to do | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Bridge code** (`whatsapp-bridge/*.go`) and you run `go run .` | Nothing — `go run` recompiles each launch. Just restart the bridge. | | **Bridge code** and you run a built binary | `cd whatsapp-bridge && go build -o whatsapp-bridge && ./whatsapp-bridge` | | **MCP server** (`whatsapp-mcp-server/*.py`, `pyproject.toml`, `uv.lock`) | Restart Claude Desktop / Cursor — `uv` re-resolves from the lockfile on next launch. Force a sync with `cd whatsapp-mcp-server && uv sync` if needed. |

Updates do **not** require re-pairing or deleting `whatsapp.db` — your session and message history are preserved. Re-pairing is only needed when explicitly requesting full history (see [Requesting full history](#requesting-full-history)).

For `v0.2.1` and later, restart both the bridge and MCP server after updating so the MCP server can read the bridge token. If the two components do not share the same checkout, set the same `WHATSAPP_BRIDGE_TOKEN` value in both environments.

Cursor IDE Configuration

Add to your Cursor MCP settings (`~/.cursor/mcp.json`):

{
  "mcp": {
    "servers": {
      "whatsapp": {
        "command": "uv",
        "args": [
          "--directory",
          "/path/to/whatsapp-mcp/whatsapp-mcp-server",
          "run",
          "main.py"
        ]
      }
    }
  }
}

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 · 1,177 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # WhatsApp MCP Server
  2. [![CI](https://github.com/verygoodplugins/whatsapp-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/verygoodplugins/whatsapp-mcp/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  5. [![Go 1.26+](https://img.shields.io/badge/go-1.26+-00ADD8.svg)](https://go.dev/)
  6. A Model Context Protocol (MCP) server for WhatsApp, enabling Claude to read and send WhatsApp messages.
  7. > Originally created by [Luke Harries](https://github.com/lharries/whatsapp-mcp). Maintained by [Very Good Plugins](https://verygoodplugins.com/?utm_source=github).
  8. <p align="center">
  9. <a href="https://github.com/user-attachments/assets/9475af1d-2369-4315-9ccc-823dba2c5c32"><strong>Watch the WhatsApp MCP demo video</strong></a>
  10. </p>
  11. <p align="center">
  12. <sub>Product demo generated with Remotion using simulated data.</sub>
  13. </p>
  14. ## Features
  15. - **Message Management**: Search and read personal WhatsApp messages (text, images, videos, documents, audio)
  16. - **Contact Search**: Search contacts by name or phone number with `sender_display` format ("Name (phone)")
  17. - **Send Messages**: Send text messages to individuals or groups
  18. - **Read Receipts**: Explicitly mark selected messages as read across linked devices
  19. - **Media Support**: Send and download images, videos, documents, and voice messages
  20. - **Call History**: Capture incoming voice/video calls into a local SQLite table (live, 1:1 and group)
  21. - **Webhook Integration**: Forward incoming messages to external services
  22. - **Local Storage**: All messages stored locally in SQLite - only sent to Claude when you allow it
  23. ## Installation
  24. ### Prerequisites
  25. - Go 1.26+
  26. - Python 3.11+
  27. - [uv](https://docs.astral.sh/uv/) package manager
  28. - Claude Desktop or Cursor
  29. - FFmpeg (optional, for voice message conversion)
  30. **Intel macOS:** patched `cryptography` releases no longer provide Intel Mac
  31. wheels, so installation may compile this dependency from source. Install the
  32. Xcode Command Line Tools (`xcode-select --install`) and, with Homebrew,
  33. `brew install rust openssl@3 pkg-config`. Then install the Python dependencies:
  34. ```bash
  35. cd whatsapp-mcp-server
  36. OPENSSL_DIR="$(brew --prefix openssl@3)" uv sync
  37. ```
  38. Use a Rust toolchain supported by the installed `cryptography` release; see its
  39. [source-build instructions](https://cryptography.io/en/latest/installation/#building-cryptography-on-macos).
  40. Keep the patched dependency rather than restoring the old vulnerable version pin.
  41. ### Quick Start
  42. 1. **Clone the repository**
  43. ```bash
  44. git clone https://github.com/verygoodplugins/whatsapp-mcp.git
  45. cd whatsapp-mcp
  46. ```
  47. 2. **Start the WhatsApp bridge**
  48. ```bash
  49. cd whatsapp-bridge
  50. go run .
  51. ```
  52. On first start, the bridge prints and stores a local REST API token at
  53. `whatsapp-bridge/store/.bridge-token`. Scan the QR code with WhatsApp on
  54. your phone to authenticate.
  55. 3. **Configure Claude Desktop**
  56. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  57. ```json
  58. {
  59. "mcpServers": {
  60. "whatsapp": {
  61. "command": "uv",
  62. "args": [
  63. "--directory",
  64. "/path/to/whatsapp-mcp/whatsapp-mcp-server",
  65. "run",
  66. "main.py"
  67. ]
  68. }
  69. }
  70. }
  71. ```
  72. Replace `/path/to/whatsapp-mcp` with your actual path.
  73. 4. **Restart Claude Desktop**
  74. ### Updating
  75. Pull the latest changes, then refresh whichever components moved:
  76. ```bash
  77. git pull
  78. ```
  79. | You changed | What to do |
  80. | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
  81. | **Bridge code** (`whatsapp-bridge/*.go`) and you run `go run .` | Nothing — `go run` recompiles each launch. Just restart the bridge. |
  82. | **Bridge code** and you run a built binary | `cd whatsapp-bridge && go build -o whatsapp-bridge && ./whatsapp-bridge` |
  83. | **MCP server** (`whatsapp-mcp-server/*.py`, `pyproject.toml`, `uv.lock`) | Restart Claude Desktop / Cursor — `uv` re-resolves from the lockfile on next launch. Force a sync with `cd whatsapp-mcp-server && uv sync` if needed. |
  84. Updates do **not** require re-pairing or deleting `whatsapp.db` — your session and message history are preserved. Re-pairing is only needed when explicitly requesting full history (see [Requesting full history](#requesting-full-history)).
  85. For `v0.2.1` and later, restart both the bridge and MCP server after updating
  86. so the MCP server can read the bridge token. If the two components do not share
  87. the same checkout, set the same `WHATSAPP_BRIDGE_TOKEN` value in both
  88. environments.
  89. ### Cursor IDE Configuration
  90. Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
  91. ```json
  92. {
  93. "mcp": {
  94. "servers": {
  95. "whatsapp": {
  96. "command": "uv",
  97. "args": [
  98. "--directory",
  99. "/path/to/whatsapp-mcp/whatsapp-mcp-server",
  100. "run",
  101. "main.py"
  102. ]
  103. }
  104. }
  105. }
  106. }
  107. ```
  108. ## Tools
  109. Messages include `sender_display` showing "Name (phone)" format for easy identification by agents.
  110. ### Contact Operations
  111. #### `search_contacts`
  112. Search contacts by name or phone number.
  113. **Parameters:**
  114. - `query` (required): Name or phone number to search
  115. **Natural Language Examples:**
  116. - "Find contacts named John"
  117. - "Search for phone number 555-1234"
  118. - "Who has the phone number starting with +1?"
  119. #### `get_contact`
  120. Resolve a WhatsApp contact name from a phone number, LID, or full JID.
  121. **Parameters:**
  122. - `identifier` (required): Phone number, LID, or full JID (aliases: `phone_number`, `phone`)
  123. - Examples: `12025551234`, `184125298348272`, `12025551234@s.whatsapp.net`, `184125298348272@lid`
  124. **Natural Language Examples:**
  125. - "What's the name for phone number 5551234567?"
  126. - "Look up who owns this number"
  127. - "Who is 184125298348272@lid?"
  128. ### Message Operations
  129. #### `list_messages`
  130. Get messages with filters, date ranges, and sorting.
  131. **Parameters:**
  132. - `chat_jid` (optional): Filter by specific chat JID
  133. - `limit` (optional): Number of messages (default 50, max 500)
  134. - `before_date` (optional): Messages before this date (YYYY-MM-DD)
  135. - `after_date` (optional): Messages after this date (YYYY-MM-DD)
  136. - `sort_by` (optional): "newest" or "oldest" (default "newest")
  137. **Natural Language Examples:**
  138. - "Show me the last 100 messages from today"
  139. - "Get messages from the family group chat"
  140. - "Find messages from last week"
  141. #### `send_message`
  142. Send a text message to a contact or group, optionally as a quoted reply.
  143. **Parameters:**
  144. - `recipient` (required): Phone number or group JID
  145. - `message` (required): Text content to send
  146. - `quoted_message_id` (optional): ID of the message to reply to. When provided, the sent message appears as a quoted reply in WhatsApp.
  147. - `quoted_sender_jid` (optional): Full JID of the author of the quoted message. Required for group replies so WhatsApp renders the correct attribution header.
  148. - `quoted_content` (optional): Text content of the quoted message, used for the reply preview. Only plain text is supported.
  149. - `mentions` (optional): List of users to @-mention, as phone numbers with country code (e.g. `["12025551234"]`) or JIDs. For each entry the message text must contain a matching `@<number>` token (e.g. `"thanks @12025551234!"`), which recipients' devices render as a highlighted, tappable mention that also notifies the user. Only meaningful in group chats.
  150. Inbound quoted replies are stored automatically. The `quoted_message_id` field in each message returned by `list_messages` indicates which message it is replying to (or `null` for non-replies).
  151. **Natural Language Examples:**
  152. - "Send 'Hello!' to +1234567890"
  153. - "Message the team group saying 'Meeting at 3pm'"
  154. - "Reply to that message saying 'Sounds good'"
  155. #### `mark_messages_read`
  156. Mark one or more messages from the same chat and sender as read. This explicitly
  157. sends WhatsApp read receipts; reading or searching messages never does so
  158. automatically.
  159. **Parameters:**
  160. - `message_ids` (required): IDs of messages from the same chat and sender
  161. - `chat_jid` (required): JID of the chat containing the messages
  162. - `sender_jid` (required for groups): Full JID or bare phone number of the original message sender
  163. - `timestamp` (optional): RFC 3339 read timestamp; defaults to the current time
  164. **Natural Language Examples:**
  165. - "Mark those messages as read"
  166. - "Mark the last three messages from Alice in the team group as read"
  167. #### `send_reaction`
  168. Send (or remove) an emoji reaction to a message.
  169. **Parameters:**
  170. - `recipient` (required): Chat JID the message belongs to (phone JID or group JID)
  171. - `message_id` (required): ID of the message to react to
  172. - `emoji` (required): Reaction emoji (e.g. `"👍"`). Pass an empty string `""` to remove an existing reaction.
  173. - `from_me` (optional, default `false`): Whether the original message was sent by the current user
  174. - `sender_jid` (optional): Full JID of the original message sender — required for group messages when `from_me` is `false` so the correct WhatsApp key is built
  175. Inbound reactions received from others are stored automatically as messages with `media_type = "reaction"`. The `reaction_to_message_id` field in each reaction message indicates which message was reacted to.
  176. When webhook forwarding is enabled, inbound reactions are also posted to `WEBHOOK_URL` as typed events. Reaction removals use an empty `content`/`reactionEmoji` and `reactionRemoved: true`.
  177. ```json
  178. {
  179. "eventType": "reaction",
  180. "sender": "15551234567",
  181. "chatJID": "15551234567@s.whatsapp.net",
  182. "isFromMe": true,
  183. "content": "👍",
  184. "messageId": "reaction-stanza-id",
  185. "mediaType": "reaction",
  186. "reactionToMessageId": "target-message-id",
  187. "reactionEmoji": "👍",
  188. "reactionRemoved": false
  189. }
  190. ```
  191. **Natural Language Examples:**
  192. - "React to that message with a thumbs up"
  193. - "Remove my reaction from the last message in the group chat"
  194. #### `send_file`
  195. Send a media file (image, video, document).
  196. Successfully sent attachments retain their download metadata in local history.
  197. Use their message ID and chat JID with `download_media` to retrieve the uploaded
  198. bytes again while WhatsApp still serves the attachment. This also applies to
  199. voice messages sent with `send_audio_message`. It does not backfill metadata for
  200. attachments sent by older bridge versions or prevent WhatsApp media expiry.
  201. **Parameters:**
  202. - `recipient` (required): Phone number or group JID
  203. - `file_path` (required): Path to the file
  204. - `caption` (optional): Caption for the media
  205. The bridge only reads files inside configured media roots. By default this is
  206. `~/.local/share/whatsapp-mcp/outbox`; set `WHATSAPP_MEDIA_ROOTS` to allow
  207. additional absolute directories.
  208. For documents, recipients receive only the filename portion of `file_path`;
  209. parent directories are not exposed.
  210. #### `send_audio_message`
  211. Send a voice message (automatically converts to Opus .ogg format).
  212. **Parameters:**
  213. - `recipient` (required): Phone number or group JID
  214. - `file_path` (required): Path to audio file
  215. Converted audio is sent through the same media-path confinement as
  216. `send_file`.
  217. #### `download_media`
  218. Download media from a received message. Returns the **local file path**, which
  219. only helps a client that can read the filesystem — use `view_media` otherwise.
  220. **Parameters:**
  221. - `message_id` (required): ID of the message with media
  222. - `chat_jid` (required): JID of the chat containing the message
  223. #### `view_media`
  224. View the media of a message as an image, for clients with no filesystem access
  225. (Claude Desktop, a claude.ai chat). Images are returned as image content;
  226. a video returns its first frame as a still. Both are downscaled first so one
  227. photo cannot flood the context. Audio is rejected with a pointer to its
  228. transcript.
  229. Uses FFmpeg when available (already an optional dependency); without it, images
  230. below 4 MB are returned unchanged and anything else reports what is missing.
  231. **Parameters:**
  232. - `message_id` (required): ID of the message with media
  233. - `chat_jid` (required): JID of the chat containing the message
  234. - `max_dimension` (optional): longest edge in pixels, default `1024`
  235. `max_dimension` must be an integer from `1` to `2048`. Invalid values are
  236. rejected before the server downloads or renders any media.
  237. #### `transcribe_audio`
  238. Transcribe a voice note with whisper.cpp (the default) or an OpenAI-compatible
  239. endpoint and return its text. The transcript is also written into the message's
  240. empty `content` field, so afterwards it is readable through `list_messages`
  241. by any client — including one with no filesystem access — without transcribing
  242. again. whisper.cpp runs entirely on this machine; the HTTP provider sends audio
  243. to the endpoint you configure. Use a loopback URL to keep transcription local.
  244. A stored transcript is returned immediately; a fresh one took about 2 s for a
  245. 30-second note with `large-v3-turbo` on an M-series Mac. Transcripts are
  246. prefixed with `[transcript (whisper <model>)]` or
  247. `[transcript (openai_compatible <model>)]` so they cannot be mistaken for
  248. text a human typed, and a real message is never overwritten.
  249. **Requirements:** [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
  250. (`whisper-cli` on `PATH`), FFmpeg, and `WHISPER_MODEL` pointing at a model
  251. file. Optionally `WHISPER_LANGUAGE` (default `auto`).
  252. To reuse an existing service, such as a local Parakeet server, configure:
  253. ```env
  254. WHATSAPP_TRANSCRIPTION_PROVIDER=openai_compatible
  255. WHATSAPP_TRANSCRIPTION_URL=http://127.0.0.1:8178/v1/audio/transcriptions
  256. WHATSAPP_TRANSCRIPTION_MODEL=parakeet
  257. ```
  258. `WHATSAPP_TRANSCRIPTION_PROVIDER` defaults to `whisper_cpp`. For
  259. `openai_compatible`, URL and MODEL are required. URL is the **full endpoint**;
  260. no path is appended. Optional `WHATSAPP_TRANSCRIPTION_API_KEY` supplies a bearer
  261. token, and `WHATSAPP_TRANSCRIPTION_LANGUAGE` supplies a language code (`auto`
  262. by default, omitted from the HTTP request). This provider uploads the original
  263. audio using multipart `file`, `model`, and `response_format=json`; the server
  264. must decode it (including WhatsApp Opus/OGG) and return `{"text": "..."}`.
  265. It requires no local whisper.cpp, model file, or FFmpeg. Remote URLs send audio
  266. off the machine; redirects, environment proxies, `.netrc` credentials, and
  267. automatic provider fallbacks are disabled.
  268. HTTP connections time out after 10 seconds, HTTP reads and Whisper inference
  269. after 300 seconds, and local FFmpeg decoding after 60 seconds.
  270. Stored transcripts are reused across provider changes unless `force=true`.
  271. Cache reads and writes use both message ID and chat JID.
  272. **Parameters:**
  273. - `message_id` (required): ID of the message with the voice note
  274. - `chat_jid` (required): JID of the chat containing the message
  275. - `force` (optional): transcribe again even when a transcript is stored
  276. ### Chat Operations
  277. All chat tools (`list_chats`, `get_chat`, `get_direct_chat_by_contact`,
  278. `get_contact_chats`) return the same chat shape:
  279. ```jsonc
  280. {
  281. "jid": "1234567890@s.whatsapp.net",
  282. "name": "Alice",
  283. "is_group": false,
  284. "last_message_time": "2024-01-15T10:30:00+00:00",
  285. "last_message": "hello world", // null when include_last_message=false
  286. "last_sender": "1234567890", // null when include_last_message=false
  287. "last_is_from_me": false,
  288. "last_read_time": "2024-01-15T09:00:00+00:00", // how far the chat is read
  289. "unread": true // last message is inbound and unread
  290. }
  291. ```
  292. #### Read state (`last_read_time` / `unread`)
  293. `last_read_time` is the bridge's read marker for the chat, fed by read
  294. receipts from your own devices and backfilled from history sync. `unread` is
  295. derived from it: true when the chat's last message is inbound and newer than
  296. the marker. This distinguishes a genuinely unread chat from one whose last
  297. message merely happens to be inbound but was already read on the phone.
  298. Caveats:
  299. - **The marker only moves forward.** Marking an already-read chat as *unread*
  300. again on the phone is not reflected.
  301. - **No marker means no read was ever reported** — for a chat with an inbound
  302. last message, `unread` then falls back to the old heuristic and reports
  303. true. Stores written by a bridge older than the `chats.last_read_time`
  304. column report `last_read_time: null` and behave the same way.
  305. - **`unread` is a chat-level flag, not an unread count.** WhatsApp's unread
  306. counter is not persisted.
  307. #### `list_chats`
  308. List all chats with metadata.
  309. **Parameters:**
  310. - `limit` (optional): Number of chats (default 50, max 200)
  311. #### `get_chat`
  312. Get specific chat metadata by JID.
  313. **Parameters:**
  314. - `jid` (required): Chat JID
  315. #### `get_direct_chat_by_contact`
  316. Find a direct message chat with a contact.
  317. **Parameters:**
  318. - `phone` (required): Phone number of the contact
  319. #### `get_contact_chats`
  320. List all chats involving a specific contact.
  321. **Parameters:**
  322. - `phone` (required): Phone number of the contact
  323. #### `get_last_interaction`
  324. Get the last message exchanged with a contact.
  325. **Parameters:**
  326. - `phone` (required): Phone number of the contact
  327. #### `get_message_context`
  328. Get messages around a specific message for context.
  329. **Parameters:**
  330. - `message_id` (required): ID of the target message
  331. - `chat_jid` (required): JID of the chat
  332. - `before` (optional): Number of messages before (default 5)
  333. - `after` (optional): Number of messages after (default 5)
  334. ## Configuration
  335. Copy `.env.example` to `.env` and configure as needed:
  336. | Variable | Default | Description |
  337. | ---------------------- | ---------------------------------------- | -------------------------------------------- |
  338. | `WHATSAPP_BRIDGE_PORT` | `8080` | Port for Go bridge REST API |
  339. | `WEBHOOK_URL` | `http://localhost:8769/whatsapp/webhook` | Webhook for incoming messages |
  340. | `WEBHOOK_ENABLED` | `true` | Set to `false` to disable outbound webhooks |
  341. | `WHATSAPP_AUTO_DOWNLOAD_MEDIA` | `true` | Automatically download incoming media, including webhook image bytes. `false` keeps webhook metadata/text without `mediaBase64` and leaves downloads to `/api/download` (`download_media`); delayed downloads may fail after media expires. Status messages are stored but never auto-downloaded or forwarded |
  342. | `FORWARD_SELF` | `true` | Forward messages sent by self |
  343. | `WHATSAPP_DB_PATH` | `../whatsapp-bridge/store/messages.db` | Path to SQLite database |
  344. | `WHATSMEOW_DB_PATH` | `../whatsapp-bridge/store/whatsapp.db` | whatsmeow DB used for LID ↔ phone resolution |
  345. | `WHATSAPP_API_URL` | `http://localhost:8080/api` | Go bridge REST API URL |
  346. | `WHATSAPP_BRIDGE_TOKEN` | generated next to `WHATSMEOW_DB_PATH` as `.bridge-token` | Bearer token for bridge REST calls; also signed onto outbound webhook POSTs |
  347. | `WHATSAPP_HUB_URL` | `http://localhost:8767/ui/whatsapp` | AutoHub status/pairing page opened by macOS bridge notifications |
  348. | `WHATSAPP_MEDIA_ROOTS` | `~/.local/share/whatsapp-mcp/outbox` | Path-list of directories allowed for outbound media files |
  349. | `WHATSAPP_DEVICE_NAME` | `whatsmeow` (whatsmeow default) | Label shown for this connection under WhatsApp > Linked Devices. Set to a recognisable name. Applies at pair time only (re-pair to change) |
  350. | `WHATSAPP_MCP_TRANSPORT` | `stdio` | MCP transport to serve clients: `stdio`, `http`, or `sse` |
  351. | `WHATSAPP_MCP_HOST` | `127.0.0.1` | Bind address for the `http`/`sse` transports |
  352. | `WHATSAPP_MCP_PORT` | `8000` | Port for the `http`/`sse` transports |
  353. | `WHATSAPP_PARENT_WATCHDOG_S` | `30` | Stdio parent-liveness poll interval (seconds); exits on parent reparent only |
  354. ### MCP transport (stdio vs http/sse)
  355. By default the server speaks MCP over **stdio**, which is what local clients
  356. like Claude Desktop and Cursor launch. To serve the server over the network
  357. instead, set `WHATSAPP_MCP_TRANSPORT`:
  358. ```bash
  359. # Streamable HTTP (current spec transport for remote MCP), endpoint at /mcp
  360. WHATSAPP_MCP_TRANSPORT=http WHATSAPP_MCP_PORT=8000 uv run main.py
  361. # Legacy Server-Sent Events transport (deprecated in the MCP spec), endpoint at /sse
  362. WHATSAPP_MCP_TRANSPORT=sse uv run main.py
  363. ```
  364. `http` is an alias for the spec's `streamable-http` transport and is the
  365. recommended choice for remote connections; `sse` is kept for older clients.
  366. > **Security:** `WHATSAPP_MCP_HOST` defaults to `127.0.0.1`, so the HTTP/SSE
  367. > server is reachable only from the local machine. The server has no built-in
  368. > authentication, and the underlying bridge can read and send WhatsApp messages
  369. > on your account. Only bind to a non-loopback address (e.g. `0.0.0.0`) if you
  370. > place an authenticating reverse proxy or tunnel in front of it.
  371. ### Bridge authentication and media paths
  372. The bridge requires bearer-token authentication for every `/api/*` request and
  373. accepts only exact loopback Host headers for its configured port. This protects
  374. the local REST API from other local processes and browser DNS-rebinding attacks.
  375. On first start, the bridge generates a 256-bit token, writes it to
  376. `.bridge-token` in the active bridge store directory with owner-only
  377. permissions, and prints a setup banner. The MCP server reads
  378. `WHATSAPP_BRIDGE_TOKEN` first, then falls back to `.bridge-token` in the same
  379. directory as `WHATSMEOW_DB_PATH`. For split deployments, containers, or process
  380. managers that do not share the store directory, set the same
  381. `WHATSAPP_BRIDGE_TOKEN` value for both the bridge and MCP server.
  382. The bridge also signs its **outbound** webhook POSTs (to `WEBHOOK_URL`) with this
  383. same token, sent as an `X-Bridge-Token: <token>` header — a dedicated header
  384. rather than `Authorization`, so it never collides with a receiver's own
  385. Authorization-based auth (e.g. HTTP Basic auth embedded in `WEBHOOK_URL` as
  386. `http://user:pass@host/...`, which `net/http` applies automatically as long as
  387. the bridge doesn't set its own `Authorization` header). The header is attached only when a token is configured **and** `WEBHOOK_URL` was
  388. explicitly set — never to the built-in local default. The bridge token also
  389. authorizes `/api/*` calls like sending messages, and nothing has vetted the
  390. implicit default address, so it must never be handed to whatever process
  391. happens to be listening there. Upgrades that predate the token rollout, or
  392. that never set `WEBHOOK_URL`, keep working unchanged. The webhook client also
  393. never follows redirects, so a misconfigured or malicious endpoint can't
  394. redirect the bridge into leaking the token to a different host. If your
  395. webhook receiver enforces the token, set its copy to this exact value: e.g.
  396. the AutoHub hub's `WHATSAPP_BRIDGE_TOKEN` must equal this bridge's token (from
  397. `.bridge-token` or its own env) — the hub accepts it via `X-Bridge-Token` or
  398. `Authorization: Bearer`. The bridge always sends the token it has; the hub
  399. rejects unauthenticated forwards only once its `WHATSAPP_BRIDGE_TOKEN` is set
  400. to the matching value.
  401. Outbound `media_path` values are confined to `WHATSAPP_MEDIA_ROOTS`. The default
  402. outbox is `~/.local/share/whatsapp-mcp/outbox`, created on bridge startup. Move
  403. files there before calling `send_file` or `send_audio_message`, or set
  404. `WHATSAPP_MEDIA_ROOTS` to a colon-separated list of absolute directories.
  405. ### Connection status and phone linking
  406. The authenticated bridge API remains available before linking:
  407. - `GET /api/connection` returns `state`, `connected`, `paired`, `message`,
  408. `qrCode`, `qrExpiresAt`, `updatedAt`, and `lastError` (`code`/`message` or null).
  409. States are `connected`, `pairing`, `logged_out`, `disconnected`, `outdated`,
  410. `connecting`, and `error`. QR values expire and refresh automatically; responses
  411. use `Cache-Control: no-store`. Treat the QR as a short-lived pairing secret.
  412. - `POST /api/connection/reconnect` retries the saved session or requests a new
  413. pairing QR if unpaired. Repeated requests share one connection attempt. It
  414. never deletes the databases or logs QR data when running in the background.
  415. - `GET /api/health` keeps its 200/503 readiness behavior and includes the current
  416. `state`, `paired`, `message`, and `lastError`, without QR data.
  417. AutoHub displays this status and QR at `/ui/whatsapp`. From your phone, use
  418. WhatsApp **Linked Devices → Link a Device**. A healthy existing session reconnects
  419. without scanning a new QR.
  420. ### Where runtime data is stored
  421. The bridge keeps its runtime state in `store/`, resolved **relative to its
  422. working directory**. `WHATSAPP_DB_PATH` and `WHATSMEOW_DB_PATH` configure the
  423. MCP server's reads; they do not change the bridge's store location. That
  424. store contains:
  425. | Path | Contents |
  426. | --- | --- |
  427. | `whatsapp.db` | whatsmeow session state, including linked-device credentials |
  428. | `messages.db` | locally synced chat and message history |
  429. | `<chat_jid>/` | downloaded images, voice notes, documents, and other media |
  430. | `.bridge-token` | the generated REST API bearer token, unless supplied through the environment |
  431. The application does not encrypt these files at rest. Anyone who can read
  432. `whatsapp.db` can obtain the linked-device credentials. Moving the store does
  433. not automatically tighten permissions on existing files; check the destination's
  434. access permissions as part of the move. An encrypted volume adds protection
  435. when the machine or a backup is lost.
  436. > **Cloud-synced folders:** a checkout inside Google Drive, Dropbox, iCloud
  437. > Drive, or OneDrive puts the default store within that service's sync scope.
  438. > Keep the checkout or its runtime store outside synced folders. Relocating
  439. > prevents future sync of that store; it does not remove copies or version
  440. > history already uploaded to a provider.
  441. #### Relocate an existing installation
  442. 1. **Stop the bridge and every MCP server before copying or moving any files.**
  443. Quit clients that launch the stdio server (such as Claude Desktop or Cursor),
  444. stop any standalone HTTP/SSE MCP server, and disable automatic restarts while
  445. migrating. The macOS jobs only manage the bridge and its monitor, so stopping
  446. them does not stop MCP clients. If installed, unload both jobs:
  447. ```bash
  448. launchctl bootout "gui/$(id -u)/com.whatsapp-mcp.bridge-monitor"
  449. launchctl bootout "gui/$(id -u)/com.whatsapp-mcp.bridge"
  450. ```
  451. For a manually started bridge, stop it in its terminal. Confirm all bridge
  452. and MCP server processes have exited. Never copy live SQLite databases.
  453. 2. Build the binary and move the **entire existing store**, including hidden
  454. files and any SQLite `-wal`, `-shm`, or journal files, to an unsynced directory.
  455. Replace the checkout path below, and use the same terminal for later examples.
  456. If you already run the bridge from another working directory, use that
  457. directory's `store/` as the source instead.
  458. ```bash
  459. repo_dir="/absolute/path/to/whatsapp-mcp"
  460. runtime_dir="$HOME/.local/share/whatsapp-mcp/runtime"
  461. (
  462. set -eu
  463. cd "$repo_dir/whatsapp-bridge"
  464. go build -o whatsapp-bridge .
  465. mkdir -p "$runtime_dir"
  466. chmod 700 "$runtime_dir"
  467. if [ -e "$runtime_dir/store" ] || [ -L "$runtime_dir/store" ]; then
  468. echo "Destination store already exists; stop and inspect it before migrating." >&2
  469. exit 1
  470. fi
  471. mv "$repo_dir/whatsapp-bridge/store" "$runtime_dir/store"
  472. )
  473. ```
  474. Continue only if the move succeeds. Do not merge two stores or start with an
  475. empty store to relocate an existing session: that creates a new session and
  476. loses access to the existing local history.
  477. 3. In **every MCP client or server configuration**, set both database paths to
  478. the moved files, using absolute paths (JSON does not expand `$HOME` or `~`):
  479. ```json
  480. "env": {
  481. "WHATSAPP_DB_PATH": "/Users/you/.local/share/whatsapp-mcp/runtime/store/messages.db",
  482. "WHATSMEOW_DB_PATH": "/Users/you/.local/share/whatsapp-mcp/runtime/store/whatsapp.db"
  483. }
  484. ```
  485. The MCP server reads `.bridge-token` beside `WHATSMEOW_DB_PATH` when
  486. `WHATSAPP_BRIDGE_TOKEN` is unset. An explicit token takes precedence: preserve
  487. the same value in the bridge, MCP clients, and any authenticated webhook
  488. receiver. Keep token values private.
  489. 4. Choose how to restart the bridge, then restart the MCP servers and clients
  490. with their updated configuration:
  491. **Manual:** launch the built binary from the new runtime directory:
  492. ```bash
  493. cd "$runtime_dir"
  494. "$repo_dir/whatsapp-bridge/whatsapp-bridge"
  495. ```
  496. **macOS launchd:** before reloading either job, edit
  497. `~/Library/Application Support/whatsapp-mcp/launchd.env` to set
  498. `WHATSAPP_BRIDGE_DIR` to the absolute runtime directory. Keep
  499. `WHATSAPP_BRIDGE_BINARY` pointing to the built binary in the checkout.
  500. The runner explicitly executes `cd "$WHATSAPP_BRIDGE_DIR"`; changing only
  501. the plist's `WorkingDirectory` does not relocate the store. Update that
  502. plist value too so both directory settings agree:
  503. ```bash
  504. /usr/libexec/PlistBuddy -c "Set :WorkingDirectory $runtime_dir" \
  505. "$HOME/Library/LaunchAgents/com.whatsapp-mcp.bridge.plist"
  506. ```
  507. Recent installers also capture `WHATSAPP_BRIDGE_TOKEN` in `launchd.env`,
  508. which both the runner and monitor source. For a generated file token, ensure
  509. that cached value matches the moved `store/.bridge-token`; update a stale
  510. cached value privately before restarting. For an explicitly configured
  511. token, retain the same override in all consumers. Changing
  512. `WHATSAPP_BRIDGE_DIR` alone does not update the cached token. Keep
  513. `launchd.env` owner-readable/writable only (`chmod 600`).
  514. ```bash
  515. launchctl bootstrap "gui/$(id -u)" \
  516. "$HOME/Library/LaunchAgents/com.whatsapp-mcp.bridge.plist"
  517. launchctl bootstrap "gui/$(id -u)" \
  518. "$HOME/Library/LaunchAgents/com.whatsapp-mcp.bridge-monitor.plist"
  519. ```
  520. Check that the bridge reconnects with the existing session and that the MCP
  521. client can read known history. An unexpected QR pairing prompt or empty
  522. history is a reason to stop and recheck paths before proceeding.
  523. **Reinstalling:** the installer preserves existing runtime/store paths and saved
  524. settings from `launchd.env`; explicitly exported values override saved settings.
  525. It builds from the current checkout into the saved binary path. Existing session
  526. and message databases are left in place.
  527. **Fresh manual installation:** only when there is no session or history to
  528. preserve, omit the `mv` step, create the runtime directory, and launch the built
  529. binary there. Pair the new device, then point the MCP server at the new databases
  530. and token as above. This is separate from migrating an existing installation.
  531. ### Run automatically on macOS
  532. macOS users can install optional per-user `launchd` jobs that start the Go
  533. bridge at login and monitor it every 60 seconds for API health, disconnects, and
  534. QR relink signals. The installer does not require `sudo` and does not install or
  535. start the MCP server.
  536. ```bash
  537. scripts/install-launchd-macos.sh
  538. ```
  539. The installer builds `whatsapp-bridge/whatsapp-bridge` with `go build` when Go is
  540. available, writes generated support files to
  541. `~/Library/Application Support/whatsapp-mcp/`, writes LaunchAgents to
  542. `~/Library/LaunchAgents/`, and writes logs to `~/Library/Logs/whatsapp-mcp/`.
  543. It safely reloads only these labels:
  544. - `com.whatsapp-mcp.bridge`
  545. - `com.whatsapp-mcp.bridge-monitor`
  546. To customize the launchd environment, export values before running the installer.
  547. Re-run the installer after changing them; saved values are otherwise preserved.
  548. ```bash
  549. export WHATSAPP_BRIDGE_PORT=8080
  550. export WEBHOOK_URL=http://localhost:8769/whatsapp/webhook
  551. export FORWARD_SELF=false
  552. export WHATSAPP_MEDIA_ROOTS="$HOME/.local/share/whatsapp-mcp/outbox"
  553. scripts/install-launchd-macos.sh
  554. ```
  555. Verify the jobs and inspect logs:
  556. ```bash
  557. launchctl print gui/$(id -u)/com.whatsapp-mcp.bridge
  558. launchctl print gui/$(id -u)/com.whatsapp-mcp.bridge-monitor
  559. tail -n 100 ~/Library/Logs/whatsapp-mcp/bridge.err.log
  560. tail -n 100 ~/Library/Logs/whatsapp-mcp/monitor.err.log
  561. ```
  562. The monitor reports the actual connection cause: an outdated client needs a
  563. bridge update; a logged-out or unpaired device needs phone linking; a temporary
  564. disconnection is retried automatically. It deduplicates repeated alerts, reminds
  565. you after six hours of persistent failure, and reports connection recovery.
  566. Notifications open `WHATSAPP_HUB_URL` when `terminal-notifier` is installed;
  567. the standard macOS fallback includes the same URL in its text.
  568. If `store/.bridge-token` lives inside a macOS TCC-protected location (for example
  569. `~/Documents` or `~/Desktop`), the sandboxed monitor can be denied read access to
  570. it. The installer avoids this by copying the resolved token into the mode-`600`
  571. `launchd.env` so the monitor reads it from the environment; if you ever see the
  572. monitor exit without alerting, re-run the installer, or set `WHATSAPP_BRIDGE_TOKEN`
  573. explicitly before running it.
  574. Uninstall the generated LaunchAgents and support files with:
  575. ```bash
  576. scripts/uninstall-launchd-macos.sh
  577. ```
  578. Uninstall preserves `whatsapp-bridge/store/`, including WhatsApp session DBs,
  579. message DBs, media, and `.bridge-token`. Logs are left in
  580. `~/Library/Logs/whatsapp-mcp/` for manual cleanup.
  581. ### CLI flags (Go bridge)
  582. | Flag | Default | Description |
  583. | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  584. | `--full-history-pair` | `false` | Request full history at pair time. Only takes effect on a fresh pair (no existing `whatsapp.db`); no-op for already-paired sessions. The phone ultimately decides the actual history window sent — see [Requesting full history](#requesting-full-history) below. |
  585. ### Requesting full history
  586. whatsmeow's default pairing asks for "recent sync" — roughly the last 3 months, with the exact window decided by the phone. If you want to pull more history at pair time:
  587. ```bash
  588. # Stop the bridge
  589. launchctl bootout gui/$UID/com.whatsapp-mcp.bridge # or however you manage it
  590. # Back up, then remove the auth session (keeps messages.db intact)
  591. cp whatsapp-bridge/store/whatsapp.db{,.bak}
  592. rm whatsapp-bridge/store/whatsapp.db
  593. # Re-pair with the flag
  594. cd whatsapp-bridge
  595. ./whatsapp-bridge --full-history-pair
  596. # Scan the QR with WhatsApp → Settings → Linked Devices → Link a Device
  597. # Wait for "History sync complete" in the logs (can take 10-30 minutes)
  598. # Ctrl+C when sync has quiesced, then restart under your normal process manager
  599. ```
  600. Caveats:
  601. - **The phone decides the actual cap.** The flag requests up to 10 years / 100 GB, but WhatsApp's iOS primary device enforces its own retention policy. iPad companion is documented at ~1 year max; other linked devices appear to follow similar logic.
  602. - **Only effective on a fresh pair.** With `whatsapp.db` already present, no new pair handshake fires and the flag is a no-op.
  603. - **Messages the phone has deleted are not recoverable** — auto-expire, low-storage cleanup, and manual delete all leave no trace for the phone to share.
  604. History sync preserves the same supported message text as live reception,
  605. including WhatsApp Business templates, button messages, and image/video/document
  606. captions. Shared contact cards are searchable text containing the display name
  607. and phone numbers; they do not require a media download. Live contact cards
  608. retain reply context and disappearing-message settings. Raw history envelopes
  609. are unwrapped using the same parser as live events. This applies to both
  610. active and archived chats. The fix does not
  611. retroactively restore text skipped by an older bridge: the affected messages
  612. must be delivered again through history sync, subject to the phone's limits.
  613. Chat activity timestamps follow the newest history message stored as supported
  614. text or media. Protocol-only entries do not advance chat activity. Their read
  615. and disappearing-message settings are retained, while metadata-only rows are
  616. excluded from chat listings until a message or reaction is stored.
  617. ### Requesting history for a single chat (on-demand)
  618. `--full-history-pair` only applies to a fresh pair, so recovering a gap in one
  619. chat otherwise means deleting `whatsapp.db` and re-syncing everything. To ask
  620. the phone for older messages in a single chat *without* re-pairing:
  621. ```bash
  622. curl -X POST http://127.0.0.1:8080/api/history \
  623. -H "Authorization: Bearer $(cat whatsapp-bridge/store/.bridge-token)" \
  624. -H "Content-Type: application/json" \
  625. -d '{"chat_jid": "1234567890@s.whatsapp.net", "count": 50}'
  626. ```
  627. The request is anchored on the **oldest message already stored** for that chat,
  628. so the phone returns messages from before it. Call it repeatedly to page
  629. further back. Results arrive asynchronously through the normal history-sync
  630. handler and land in `messages.db` — typically within a few seconds.
  631. | Field | Required | Description |
  632. | --------- | -------- | ------------------------------------------------------ |
  633. | `chat_jid` | yes | Chat to backfill (`...@s.whatsapp.net` or `...@g.us`) |
  634. | `count` | no | Messages to request; default `50`, capped at `500` |
  635. Caveats:
  636. - **The phone decides how much it returns**, exactly as with pair-time sync, so
  637. `count` is a request rather than a guarantee.
  638. - **At least one message for the chat must already be stored**, since it is used
  639. as the anchor. Chats with no local messages return `404`; send or receive one
  640. message first.
  641. - Messages the phone has deleted are not recoverable, as above.
  642. ## Call History
  643. The bridge captures incoming WhatsApp voice and video calls live into a
  644. dedicated `calls` table in `messages.db`. When a 1:1 call arrives
  645. (`CallOffer`) or a group call is announced (`CallOfferNotice`), a row is
  646. inserted with `result='in_progress'`. Subsequent `CallAccept` /
  647. `CallReject` / `CallTerminate` events update the row — final result becomes
  648. `answered`, `rejected`, `missed`, or `ended` depending on the event
  649. sequence. See the state-machine comment above `StoreCallOffer` in `main.go`
  650. for the exact transitions.
  651. ### Schema
  652. ```sql
  653. CREATE TABLE calls (
  654. call_id TEXT,
  655. chat_jid TEXT, -- group JID for group calls, call creator JID for 1:1
  656. from_jid TEXT, -- JID of whoever started the call
  657. timestamp TIMESTAMP, -- call start time
  658. is_from_me BOOLEAN,
  659. call_type TEXT, -- 'voice' or 'video'
  660. is_group BOOLEAN,
  661. result TEXT, -- 'in_progress' | 'answered' | 'ended' |
  662. -- 'missed' | 'rejected'
  663. duration_sec INTEGER, -- computed when the call terminates
  664. ended_at TIMESTAMP,
  665. reason TEXT, -- terminate reason string from whatsmeow
  666. PRIMARY KEY (call_id, chat_jid)
  667. );
  668. ```
  669. ### Caveats
  670. - **Outbound calls are not captured.** WhatsApp's primary device handles
  671. calls it initiates without notifying linked devices, so the bridge never
  672. sees an event for them.
  673. - **Call results only reflect what the bridge saw.** If the bridge is
  674. offline when a call happens, the events are lost.
  675. - **1:1 calls default to `call_type='voice'`.** `CallOffer` events don't
  676. expose media type directly (it's buried in the binary call data). Group
  677. calls via `CallOfferNotice` include a `Media` field and are recorded
  678. accurately as voice or video.
  679. ## Architecture
  680. ```mermaid
  681. flowchart TB
  682. subgraph Clients["AI Clients"]
  683. CD[Claude Desktop]
  684. CU[Cursor IDE]
  685. CC[Claude Code]
  686. end
  687. subgraph MCP["MCP Layer"]
  688. PY[Python MCP Server<br/>FastMCP]
  689. end
  690. subgraph Bridge["WhatsApp Bridge"]
  691. GO[Go Bridge<br/>whatsmeow]
  692. DB[(SQLite<br/>messages.db)]
  693. WH[Webhook Handler]
  694. end
  695. subgraph External["External Services"]
  696. WA[WhatsApp Web API]
  697. EXT[External Webhook<br/>Receiver]
  698. end
  699. CD & CU & CC -->|MCP Protocol| PY
  700. PY -->|REST API| GO
  701. PY -->|Read| DB
  702. GO -->|Store| DB
  703. GO <-->|WebSocket| WA
  704. GO -->|Forward Messages| WH
  705. WH -->|POST| EXT
  706. ```
  707. ### Component Details
  708. ```mermaid
  709. flowchart LR
  710. subgraph GoAPI["Go Bridge REST API"]
  711. direction TB
  712. SEND["/api/send"]
  713. READ["/api/mark-read"]
  714. DOWN["/api/download"]
  715. REACT["/api/react"]
  716. TYPE["/api/typing"]
  717. HIST["/api/history"]
  718. HEALTH["/api/health"]
  719. end
  720. subgraph MCPTools["MCP Tools (15 total)"]
  721. direction TB
  722. CONT["Contact Tools<br/>search_contacts, get_contact"]
  723. MSG["Message Tools<br/>list_messages, send_message, etc."]
  724. CHAT["Chat Tools<br/>list_chats, get_chat, etc."]
  725. MEDIA["Media Tools<br/>send_file, download_media, etc."]
  726. end
  727. MCPTools -->|HTTP Requests| GoAPI
  728. ```
  729. ### Data Flow
  730. ```mermaid
  731. sequenceDiagram
  732. participant User as User
  733. participant Claude as Claude Desktop
  734. participant MCP as Python MCP Server
  735. participant Bridge as Go Bridge
  736. participant WA as WhatsApp
  737. User->>Claude: "Send 'Hello' to Mom"
  738. Claude->>MCP: send_message(recipient, message)
  739. MCP->>Bridge: POST /api/send
  740. Bridge->>WA: Send via WebSocket
  741. WA-->>Bridge: Delivery confirmation
  742. Bridge-->>MCP: Success response
  743. MCP-->>Claude: Message sent
  744. Claude-->>User: "Message sent to Mom"
  745. ```
  746. ### Incoming Message Flow
  747. ```mermaid
  748. sequenceDiagram
  749. participant WA as WhatsApp
  750. participant Bridge as Go Bridge
  751. participant DB as SQLite
  752. participant WH as Webhook
  753. participant EXT as External Service
  754. WA->>Bridge: New message
  755. Bridge->>DB: Store message
  756. Bridge->>Bridge: Auto-download media
  757. Bridge->>WH: Forward to webhook
  758. WH->>EXT: POST with message data
  759. Note over EXT: Process incoming message
  760. ```
  761. ## Development
  762. ### Running Tests
  763. ```bash
  764. cd whatsapp-mcp-server
  765. uv pip install -e ".[dev]"
  766. uv run pytest -v
  767. ```
  768. ### Linting
  769. ```bash
  770. # Python
  771. cd whatsapp-mcp-server
  772. uv run ruff check .
  773. uv run ruff format .
  774. # Go
  775. cd whatsapp-bridge
  776. golangci-lint run
  777. ```
  778. ### Building
  779. ```bash
  780. # Go bridge
  781. cd whatsapp-bridge
  782. go build -o whatsapp-bridge
  783. # Run the binary
  784. ./whatsapp-bridge
  785. # During development (avoids stale binaries)
  786. go run .
  787. ```
  788. ### Releasing (Maintainers)
  789. Releases use Release Please automation; maintainer steps and fallback procedures
  790. are documented in [docs/RELEASING.md](docs/RELEASING.md).
  791. ## Troubleshooting
  792. ### Chat names show phone numbers
  793. The bridge retries name resolution when a stored chat name is a numeric
  794. placeholder. It also repairs DMs previously named after your own account number
  795. when another message or history-sync event reaches that chat. Real stored names
  796. are preserved.
  797. ### Authentication Issues
  798. - **Pairing fails with `Client outdated` or HTTP 405**: Update to the latest
  799. release and rebuild the bridge. WhatsApp periodically raises the minimum
  800. supported linked-device client version, which can make older whatsmeow builds
  801. fail before pairing completes.
  802. - **QR Code Not Displaying**: Restart the bridge. Check terminal QR code support.
  803. - **Phone says "check your connection" after scanning**: WhatsApp answers a scan
  804. with a `companion_reg_refresh` notification, whatsmeow rotates the pairing
  805. secret, and the bridge prints a **new** QR code marked `QR code refreshed`.
  806. Scan that one — the earlier code is dead at that point. Needs a whatsmeow
  807. build from 2026-09-15 or later; older ones never emit the rotated code.
  808. - **Device Limit Reached**: Remove a linked device from WhatsApp Settings > Linked Devices.
  809. - **No Messages Loading**: Initial sync can take several minutes for large chat histories.
  810. - **MCP tools fail with `WhatsApp messages database not found`**: The MCP
  811. server opens `messages.db` read-only and refuses to create it. Start the
  812. bridge once so it creates `whatsapp-bridge/store/messages.db`, or set
  813. `WHATSAPP_DB_PATH` to wherever it lives.
  814. - **Out of Sync**: Back up `whatsapp-bridge/store`, then move
  815. `whatsapp-bridge/store/whatsapp.db` aside and re-authenticate. Keep
  816. `messages.db` unless you intentionally want to discard local message history.
  817. - **Bridge returns 401 Unauthorized**: Restart the bridge so it creates
  818. `.bridge-token` next to `WHATSMEOW_DB_PATH`, then restart the MCP server. If
  819. the MCP server cannot read that file, set `WHATSAPP_BRIDGE_TOKEN` to the same
  820. value in both environments.
  821. - **Bridge returns 403 Forbidden for Host**: Use `WHATSAPP_API_URL` with
  822. `http://127.0.0.1:<port>/api`, `http://localhost:<port>/api`, or
  823. `http://[::1]:<port>/api`; custom hostnames and missing ports are rejected.
  824. - **Bridge returns 403 Forbidden for media_path**: Move the file into
  825. `~/.local/share/whatsapp-mcp/outbox` or add its absolute parent directory to
  826. `WHATSAPP_MEDIA_ROOTS`.
  827. ### App State / LTHash Conflicts
  828. Some WhatsApp account state is managed by whatsmeow in
  829. `whatsapp-bridge/store/whatsapp.db`. If the bridge reports errors like:
  830. ```text
  831. SendAppState failed: server returned error updating app state (regular_low):
  832. <error code="409" text="conflict"/>
  833. failed to verify patch v12345: mismatching LTHash
  834. ```
  835. then WhatsApp's app-state patch chain for the linked device is out of sync.
  836. This usually affects operations that write chat settings such as archive,
  837. mute, or pin state. Incoming and outgoing messages may still work because
  838. message storage lives separately in `messages.db`.
  839. Known manual resync attempts such as `FetchAppState(..., fullSync=true)` may
  840. still fail on this upstream app-state error class. The practical recovery path
  841. is to reset the whatsmeow session and re-pair:
  842. ```bash
  843. # Stop the bridge first.
  844. launchctl bootout gui/$UID/com.whatsapp-mcp.bridge # or however you manage it
  845. # Back up the whole runtime store.
  846. cp -a whatsapp-bridge/store whatsapp-bridge/store.bak.$(date +%Y%m%d%H%M%S)
  847. # Reset only the whatsmeow session/app-state DB.
  848. mv whatsapp-bridge/store/whatsapp.db whatsapp-bridge/store/whatsapp.db.lthash.bak
  849. # Restart the bridge and scan the new QR code.
  850. cd whatsapp-bridge
  851. ./whatsapp-bridge # or `go run .` during development
  852. ```
  853. Do not remove `whatsapp-bridge/store/messages.db` for this recovery unless you
  854. also want to delete the local message archive.
  855. ### Windows
  856. Windows requires CGO for go-sqlite3. Install [MSYS2](https://www.msys2.org/) and enable CGO:
  857. ```bash
  858. go env -w CGO_ENABLED=1
  859. go run .
  860. ```
  861. ## Security Notice
  862. > **Caution**: As with many MCP servers, this is subject to [the lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). Prompt injection could lead to private data exfiltration. Use with awareness.
  863. On Unix-like systems, newly created bridge `store/` and per-chat media
  864. directories request owner-only permissions (`0700`), and newly downloaded media
  865. files request `0600`. This is local filesystem defense-in-depth; it does not
  866. encrypt data or protect it from privileged users, backups, or sync services.
  867. Existing directories and files retain their permissions: the bridge does not
  868. recursively change an existing store tree.
  869. ## License
  870. MIT License - see [LICENSE](LICENSE) for details.
  871. ## Credits & History
  872. This project is a maintained fork of [lharries/whatsapp-mcp](https://github.com/lharries/whatsapp-mcp), originally created by [Luke Harries](https://github.com/lharries).
  873. **Why we forked:** The original repository hasn't been updated since April 2025. We needed continued maintenance, bug fixes, and new features for production use.
  874. **Highlights since the fork:**
  875. - `/api/typing`, `/api/health`, and webhook forwarding (with reply context + image media)
  876. - Auto-download of incoming media with collision-safe filenames
  877. - `get_contact` tool, `sender_display` field, and LID ↔ phone resolution via the whatsmeow store
  878. - Live capture of incoming voice/video calls into a `calls` table
  879. - `--full-history-pair` flag to request extended history at pair time
  880. - Resilience: recovers from `StreamReplaced` session conflicts; pinned `anyio` to dodge a cancel-scope regression
  881. - CI/CD with GitHub Actions, Release Please for automated versioning, and Dependabot
  882. The full release-by-release list lives in [CHANGELOG.md](CHANGELOG.md).
  883. **Recent contributors** (huge thanks):
  884. - [@edmenendez](https://github.com/edmenendez) — call capture (#39), full-history flag (#37), caption surfacing (#42), media filename collisions (#40), download race fix (#41), LID matching (#43), contact resolution via whatsmeow store (#30)
  885. - [@davidsimoes](https://github.com/davidsimoes) — `StreamReplaced` recovery (#27)
  886. - [@davidggphy](https://github.com/davidggphy) — LID → phone JID consistency (#12)
  887. - [@maikol-solis](https://github.com/maikol-solis) — bridge run command fix (#23)
  888. - [@DeetBot](https://github.com/DeetBot) — `anyio` cancel-scope pin (#44)
  889. And to Luke for creating the original project. See [CONTRIBUTING.md](CONTRIBUTING.md) if you'd like to join in.
  890. ## Links
  891. - [Very Good Plugins](https://verygoodplugins.com/?utm_source=github)
  892. - [MCP Specification](https://modelcontextprotocol.io/)
  893. - [whatsmeow](https://github.com/tulir/whatsmeow) - WhatsApp Web API library for Go
  894. - [FastMCP](https://github.com/jlowin/fastmcp) - Fast Model Context Protocol implementation

Ratings and comments

Sign in to rate this skill.

Sign in

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