Skip to content
Back to search

qx-whatsapp-mcp

Unofficial, experimental WhatsApp MCP server: fork of verygoodplugins/whatsapp-mcp adding group management and WhatsApp Communities

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/quinnfrederick--qx-whatsapp-mcp"><img src="/api/listings/quinnfrederick--qx-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.

You need git, Go 1.25+, [uv](https://docs.astral.sh/uv/), a C compiler (the SQLite driver uses cgo: Xcode Command Line Tools on macOS, `build-essential` on Debian/Ubuntu) and Claude Code or Claude Desktop. FFmpeg is optional (voice notes). uv fetches Python 3.11+ if you don't have it.

1. Run the bridge and install the MCP server

git clone -b feature/group-management https://github.com/QuinnFrederick/qx-whatsapp-mcp.git
cd qx-whatsapp-mcp/whatsapp-bridge
go run .

✅ The first run compiles for a minute or two, then prints a `WHATSAPP BRIDGE AUTH TOKEN — first-time setup` box and a QR code. Leave it running. The token is saved to `store/.bridge-token`; the MCP server reads it from there, so there is nothing to copy.

In a second terminal:

cd qx-whatsapp-mcp/whatsapp-mcp-server
uv sync

✅ Finishes without errors. You don't start the MCP server yourself; Claude launches it (step 3).

2. Link your WhatsApp account

On your phone open WhatsApp → **Settings → Linked devices → Link a device** (Android: ⋮ menu → **Linked devices**) and scan the QR code in the bridge terminal. Scan within about a minute: the bridge prints only the first code.

✅ The bridge prints:

Successfully connected and authenticated!
✓ Connected to WhatsApp! Type 'help' for commands.
REST server is running. Press Ctrl+C to disconnect and exit.

and your phone lists a new linked device. Chat history then syncs in the background: recent chats within minutes, longer for big accounts. Check the bridge from another terminal (its API only starts after pairing):

cd qx-whatsapp-mcp/whatsapp-bridge
curl -s -H "Authorization: Bearer $(cat store/.bridge-token)" http://127.0.0.1:8080/api/health

✅ `{"connected":true,"status":"ok",...}`

The link persists: later runs of `go run .` reconnect without a QR code. **To re-pair** (a different account, after unlinking the device on your phone, or to fetch more history), stop the bridge with Ctrl+C and move the session aside:

mv store/whatsapp.db store/whatsapp.db.bak
go run .

A new QR code appears; `store/messages.db`, your local message archive, is kept. To name the device in your phone's list, pair with `WHATSAPP_DEVICE_NAME="My laptop" go run .`. To ask the phone for more than its default ~3 months of history, pair with `go run . --full-history-pair` ([details](#requesting-full-history)).

3. Connect it to Claude

**Claude Code**: from `qx-whatsapp-mcp/whatsapp-mcp-server`:

claude mcp add --scope user whatsapp -- uv --directory "$PWD" run main.py

✅ `claude mcp list` shows `whatsapp` as connected.

**Claude Desktop**: print the two absolute paths you need:

cd qx-whatsapp-mcp/whatsapp-mcp-server && pwd && which uv

Open **Settings → Developer → Edit Config** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add, with your paths:

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

Use the full path to `uv`: Claude Desktop doesn't inherit your shell's `PATH`. Quit Claude Desktop completely and reopen it.

✅ `whatsapp` and its tools appear in the chat box's tools menu.

Cursor: see [Cursor IDE Configuration](#cursor-ide-configuration). The claude.ai web and mobile apps need a remote HTTPS connector; this server runs locally over stdio by default (see [MCP transport](#mcp-transport-stdio-vs-httpsse)).

4. Try it

Ask Claude:

> Which of my WhatsApp chats have unread messages? Summarise them.

✅ Claude asks to use `list_chats` and `list_messages`, then answers with your real chats. If it finds none, history is still syncing; try again in a few minutes.

Reading is safe to experiment with. Sending reaches real people, so try it on yourself first:

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 · 995 lines
  1. # qx-whatsapp-mcp
  2. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  3. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  4. [![Go 1.25+](https://img.shields.io/badge/go-1.25+-00ADD8.svg)](https://go.dev/)
  5. A Model Context Protocol (MCP) server for WhatsApp, enabling Claude to read and send WhatsApp messages.
  6. > [!WARNING]
  7. > **Early, experimental software (version 0.1). Use at your own risk.**
  8. > This is an unofficial project. It is not affiliated with, endorsed by or connected to
  9. > WhatsApp or Meta. It signs in to your personal account as a linked device through an
  10. > unofficial client library ([whatsmeow](https://github.com/tulir/whatsmeow)), which can
  11. > break without notice, and WhatsApp may restrict accounts that use unofficial clients.
  12. > Fork of [verygoodplugins/whatsapp-mcp](https://github.com/verygoodplugins/whatsapp-mcp)
  13. > (itself a fork of [Luke Harries' original](https://github.com/lharries/whatsapp-mcp)) that adds
  14. > group management and WhatsApp Communities. See [`FORK.md`](./FORK.md).
  15. <p align="center">
  16. <a href="https://github.com/user-attachments/assets/9475af1d-2369-4315-9ccc-823dba2c5c32"><strong>Watch the WhatsApp MCP demo video</strong></a>
  17. </p>
  18. <p align="center">
  19. <sub>Product demo generated with Remotion using simulated data.</sub>
  20. </p>
  21. ## Features
  22. - **Message Management**: Search and read personal WhatsApp messages (text, images, videos, documents, audio)
  23. - **Contact Search**: Search contacts by name or phone number with `sender_display` format ("Name (phone)")
  24. - **Send Messages**: Send text messages to individuals or groups
  25. - **Read Receipts**: Explicitly mark selected messages as read across linked devices
  26. - **Media Support**: Send and download images, videos, documents, and voice messages
  27. - **Call History**: Capture incoming voice/video calls into a local SQLite table (live, 1:1 and group)
  28. - **Webhook Integration**: Forward incoming messages to external services
  29. - **Local Storage**: All messages stored locally in SQLite - only sent to Claude when you allow it
  30. ## Getting started
  31. You need git, Go 1.25+, [uv](https://docs.astral.sh/uv/), a C compiler (the SQLite driver
  32. uses cgo: Xcode Command Line Tools on macOS, `build-essential` on Debian/Ubuntu) and Claude
  33. Code or Claude Desktop. FFmpeg is optional (voice notes). uv fetches Python 3.11+ if you
  34. don't have it.
  35. ### 1. Run the bridge and install the MCP server
  36. ```bash
  37. git clone -b feature/group-management https://github.com/QuinnFrederick/qx-whatsapp-mcp.git
  38. cd qx-whatsapp-mcp/whatsapp-bridge
  39. go run .
  40. ```
  41. ✅ The first run compiles for a minute or two, then prints a `WHATSAPP BRIDGE AUTH TOKEN —
  42. first-time setup` box and a QR code. Leave it running. The token is saved to
  43. `store/.bridge-token`; the MCP server reads it from there, so there is nothing to copy.
  44. In a second terminal:
  45. ```bash
  46. cd qx-whatsapp-mcp/whatsapp-mcp-server
  47. uv sync
  48. ```
  49. ✅ Finishes without errors. You don't start the MCP server yourself; Claude launches it (step 3).
  50. ### 2. Link your WhatsApp account
  51. On your phone open WhatsApp → **Settings → Linked devices → Link a device** (Android: ⋮ menu →
  52. **Linked devices**) and scan the QR code in the bridge terminal. Scan within about a minute:
  53. the bridge prints only the first code.
  54. ✅ The bridge prints:
  55. ```text
  56. Successfully connected and authenticated!
  57. ✓ Connected to WhatsApp! Type 'help' for commands.
  58. REST server is running. Press Ctrl+C to disconnect and exit.
  59. ```
  60. and your phone lists a new linked device. Chat history then syncs in the background: recent
  61. chats within minutes, longer for big accounts. Check the bridge from another terminal (its API
  62. only starts after pairing):
  63. ```bash
  64. cd qx-whatsapp-mcp/whatsapp-bridge
  65. curl -s -H "Authorization: Bearer $(cat store/.bridge-token)" http://127.0.0.1:8080/api/health
  66. ```
  67. ✅ `{"connected":true,"status":"ok",...}`
  68. The link persists: later runs of `go run .` reconnect without a QR code. **To re-pair** (a
  69. different account, after unlinking the device on your phone, or to fetch more history), stop
  70. the bridge with Ctrl+C and move the session aside:
  71. ```bash
  72. mv store/whatsapp.db store/whatsapp.db.bak
  73. go run .
  74. ```
  75. A new QR code appears; `store/messages.db`, your local message archive, is kept. To name the
  76. device in your phone's list, pair with `WHATSAPP_DEVICE_NAME="My laptop" go run .`. To ask the
  77. phone for more than its default ~3 months of history, pair with `go run . --full-history-pair`
  78. ([details](#requesting-full-history)).
  79. ### 3. Connect it to Claude
  80. **Claude Code**: from `qx-whatsapp-mcp/whatsapp-mcp-server`:
  81. ```bash
  82. claude mcp add --scope user whatsapp -- uv --directory "$PWD" run main.py
  83. ```
  84. ✅ `claude mcp list` shows `whatsapp` as connected.
  85. **Claude Desktop**: print the two absolute paths you need:
  86. ```bash
  87. cd qx-whatsapp-mcp/whatsapp-mcp-server && pwd && which uv
  88. ```
  89. Open **Settings → Developer → Edit Config** (`~/Library/Application Support/Claude/claude_desktop_config.json`
  90. on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows) and add, with your paths:
  91. ```json
  92. {
  93. "mcpServers": {
  94. "whatsapp": {
  95. "command": "/absolute/path/to/uv",
  96. "args": ["--directory", "/absolute/path/to/qx-whatsapp-mcp/whatsapp-mcp-server", "run", "main.py"]
  97. }
  98. }
  99. }
  100. ```
  101. Use the full path to `uv`: Claude Desktop doesn't inherit your shell's `PATH`. Quit Claude
  102. Desktop completely and reopen it.
  103. ✅ `whatsapp` and its tools appear in the chat box's tools menu.
  104. Cursor: see [Cursor IDE Configuration](#cursor-ide-configuration). The claude.ai web and mobile
  105. apps need a remote HTTPS connector; this server runs locally over stdio by default (see
  106. [MCP transport](#mcp-transport-stdio-vs-httpsse)).
  107. ### 4. Try it
  108. Ask Claude:
  109. > Which of my WhatsApp chats have unread messages? Summarise them.
  110. ✅ Claude asks to use `list_chats` and `list_messages`, then answers with your real chats. If
  111. it finds none, history is still syncing; try again in a few minutes.
  112. Reading is safe to experiment with. Sending reaches real people, so try it on yourself first:
  113. "Send 'hello from Claude' to +<your number>" should land in your own "message yourself" chat.
  114. Then try "List my WhatsApp communities and their groups."
  115. ### Troubleshooting setup
  116. - **The QR code expired before you scanned it.** Only the first code is printed and the next
  117. attempt is minutes away: press Ctrl+C and run `go run .` again.
  118. - **The QR code is garbled.** It is drawn with Unicode block characters: widen the terminal or
  119. shrink the font.
  120. - **`Client outdated` or HTTP 405 while pairing.** WhatsApp raised its minimum client version:
  121. `git pull`, then `go run .` again.
  122. - **`cgo: C compiler "gcc" not found` or `go-sqlite3 requires cgo`.** Install a C compiler (see
  123. the start of this section; on Windows see [Windows](#windows)).
  124. - **Claude doesn't list the WhatsApp tools.** Check the paths are absolute (including `uv` for
  125. Claude Desktop), restart Claude fully, and read the server log
  126. (`~/Library/Logs/Claude/mcp-server-whatsapp.log` for Claude Desktop on macOS).
  127. - **Sending fails with `Request error … Connection refused`.** The bridge isn't running or isn't
  128. paired yet. Reading still works, because it uses the local database.
  129. - **Tools fail with `HTTP 401`.** The MCP server and the bridge are using different tokens, which
  130. happens when they aren't in the same checkout. Set `WHATSAPP_BRIDGE_TOKEN` to the contents of
  131. `whatsapp-bridge/store/.bridge-token` for the MCP server (`-e` with `claude mcp add`, an
  132. `"env"` block in the Desktop config).
  133. - **Chats or older messages are missing.** Sync may still be running, and phones share only
  134. recent history by default. See [Requesting full history](#requesting-full-history) and
  135. [single-chat history](#requesting-history-for-a-single-chat-on-demand).
  136. - **"Device limit reached" on the phone.** Unlink an old device under Linked devices.
  137. More in [Troubleshooting](#troubleshooting).
  138. ### Updating
  139. Pull the latest changes, then refresh whichever components moved:
  140. ```bash
  141. git pull
  142. ```
  143. | You changed | What to do |
  144. | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
  145. | **Bridge code** (`whatsapp-bridge/*.go`) and you run `go run .` | Nothing — `go run` recompiles each launch. Just restart the bridge. |
  146. | **Bridge code** and you run a built binary | `cd whatsapp-bridge && go build -o whatsapp-bridge && ./whatsapp-bridge` |
  147. | **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. |
  148. 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)).
  149. For `v0.2.1` and later, restart both the bridge and MCP server after updating
  150. so the MCP server can read the bridge token. If the two components do not share
  151. the same checkout, set the same `WHATSAPP_BRIDGE_TOKEN` value in both
  152. environments.
  153. ### Cursor IDE Configuration
  154. Add to your Cursor MCP settings (`~/.cursor/mcp.json`):
  155. ```json
  156. {
  157. "mcp": {
  158. "servers": {
  159. "whatsapp": {
  160. "command": "uv",
  161. "args": [
  162. "--directory",
  163. "/path/to/whatsapp-mcp/whatsapp-mcp-server",
  164. "run",
  165. "main.py"
  166. ]
  167. }
  168. }
  169. }
  170. }
  171. ```
  172. ## Tools
  173. Messages include `sender_display` showing "Name (phone)" format for easy identification by agents.
  174. ### Contact Operations
  175. #### `search_contacts`
  176. Search contacts by name or phone number.
  177. **Parameters:**
  178. - `query` (required): Name or phone number to search
  179. **Natural Language Examples:**
  180. - "Find contacts named John"
  181. - "Search for phone number 555-1234"
  182. - "Who has the phone number starting with +1?"
  183. #### `get_contact`
  184. Resolve a WhatsApp contact name from a phone number, LID, or full JID.
  185. **Parameters:**
  186. - `identifier` (required): Phone number, LID, or full JID (aliases: `phone_number`, `phone`)
  187. - Examples: `12025551234`, `184125298348272`, `12025551234@s.whatsapp.net`, `184125298348272@lid`
  188. **Natural Language Examples:**
  189. - "What's the name for phone number 5551234567?"
  190. - "Look up who owns this number"
  191. - "Who is 184125298348272@lid?"
  192. ### Message Operations
  193. #### `list_messages`
  194. Get messages with filters, date ranges, and sorting.
  195. **Parameters:**
  196. - `chat_jid` (optional): Filter by specific chat JID
  197. - `limit` (optional): Number of messages (default 50, max 500)
  198. - `before_date` (optional): Messages before this date (YYYY-MM-DD)
  199. - `after_date` (optional): Messages after this date (YYYY-MM-DD)
  200. - `sort_by` (optional): "newest" or "oldest" (default "newest")
  201. **Natural Language Examples:**
  202. - "Show me the last 100 messages from today"
  203. - "Get messages from the family group chat"
  204. - "Find messages from last week"
  205. #### `send_message`
  206. Send a text message to a contact or group, optionally as a quoted reply.
  207. **Parameters:**
  208. - `recipient` (required): Phone number or group JID
  209. - `message` (required): Text content to send
  210. - `quoted_message_id` (optional): ID of the message to reply to. When provided, the sent message appears as a quoted reply in WhatsApp.
  211. - `quoted_sender_jid` (optional): Full JID of the author of the quoted message. Required for group replies so WhatsApp renders the correct attribution header.
  212. - `quoted_content` (optional): Text content of the quoted message, used for the reply preview. Only plain text is supported.
  213. - `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.
  214. 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).
  215. **Natural Language Examples:**
  216. - "Send 'Hello!' to +1234567890"
  217. - "Message the team group saying 'Meeting at 3pm'"
  218. - "Reply to that message saying 'Sounds good'"
  219. #### `mark_messages_read`
  220. Mark one or more messages from the same chat and sender as read. This explicitly
  221. sends WhatsApp read receipts; reading or searching messages never does so
  222. automatically.
  223. **Parameters:**
  224. - `message_ids` (required): IDs of messages from the same chat and sender
  225. - `chat_jid` (required): JID of the chat containing the messages
  226. - `sender_jid` (required for groups): Full JID or bare phone number of the original message sender
  227. - `timestamp` (optional): RFC 3339 read timestamp; defaults to the current time
  228. **Natural Language Examples:**
  229. - "Mark those messages as read"
  230. - "Mark the last three messages from Alice in the team group as read"
  231. #### `send_reaction`
  232. Send (or remove) an emoji reaction to a message.
  233. **Parameters:**
  234. - `recipient` (required): Chat JID the message belongs to (phone JID or group JID)
  235. - `message_id` (required): ID of the message to react to
  236. - `emoji` (required): Reaction emoji (e.g. `"👍"`). Pass an empty string `""` to remove an existing reaction.
  237. - `from_me` (optional, default `false`): Whether the original message was sent by the current user
  238. - `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
  239. 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.
  240. 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`.
  241. ```json
  242. {
  243. "eventType": "reaction",
  244. "sender": "15551234567",
  245. "chatJID": "15551234567@s.whatsapp.net",
  246. "isFromMe": true,
  247. "content": "👍",
  248. "messageId": "reaction-stanza-id",
  249. "mediaType": "reaction",
  250. "reactionToMessageId": "target-message-id",
  251. "reactionEmoji": "👍",
  252. "reactionRemoved": false
  253. }
  254. ```
  255. **Natural Language Examples:**
  256. - "React to that message with a thumbs up"
  257. - "Remove my reaction from the last message in the group chat"
  258. #### `send_file`
  259. Send a media file (image, video, document).
  260. **Parameters:**
  261. - `recipient` (required): Phone number or group JID
  262. - `file_path` (required): Path to the file
  263. - `caption` (optional): Caption for the media
  264. The bridge only reads files inside configured media roots. By default this is
  265. `~/.local/share/whatsapp-mcp/outbox`; set `WHATSAPP_MEDIA_ROOTS` to allow
  266. additional absolute directories.
  267. #### `send_audio_message`
  268. Send a voice message (automatically converts to Opus .ogg format).
  269. **Parameters:**
  270. - `recipient` (required): Phone number or group JID
  271. - `file_path` (required): Path to audio file
  272. Converted audio is sent through the same media-path confinement as
  273. `send_file`.
  274. #### `download_media`
  275. Download media from a received message.
  276. **Parameters:**
  277. - `message_id` (required): ID of the message with media
  278. - `chat_jid` (required): JID of the chat containing the message
  279. ### Group Operations (fork)
  280. This fork adds group management, WhatsApp Communities and profile pictures:
  281. `resolve_contacts` (turn spoken names into contacts and flag ambiguous ones, with avatar
  282. thumbnails), `get_profile_picture`, `create_group` (optionally inside a community),
  283. `update_group_settings`, `update_group_participants`, `get_group_invite_link`,
  284. `set_group_picture` (set or remove a group's or community's picture from a URL, a local
  285. file or base64; any JPEG, PNG or WebP is cropped and converted for you),
  286. `list_communities`, `list_community_participants`, `create_community` and
  287. `update_community_groups`. Tool parameters, the bridge endpoints behind them
  288. (`/api/group/*`, `/api/community/*`, `/api/communities`, `/api/profile-picture`), their JSON
  289. shapes and what WhatsApp does not allow are documented in [`FORK.md`](./FORK.md).
  290. ### Chat Operations
  291. All chat tools (`list_chats`, `get_chat`, `get_direct_chat_by_contact`,
  292. `get_contact_chats`) return the same chat shape:
  293. ```jsonc
  294. {
  295. "jid": "1234567890@s.whatsapp.net",
  296. "name": "Alice",
  297. "is_group": false,
  298. "last_message_time": "2024-01-15T10:30:00+00:00",
  299. "last_message": "hello world", // null when include_last_message=false
  300. "last_sender": "1234567890", // null when include_last_message=false
  301. "last_is_from_me": false,
  302. "last_read_time": "2024-01-15T09:00:00+00:00", // how far the chat is read
  303. "unread": true // last message is inbound and unread
  304. }
  305. ```
  306. #### Read state (`last_read_time` / `unread`)
  307. `last_read_time` is the bridge's read marker for the chat, fed by read
  308. receipts from your own devices and backfilled from history sync. `unread` is
  309. derived from it: true when the chat's last message is inbound and newer than
  310. the marker. This distinguishes a genuinely unread chat from one whose last
  311. message merely happens to be inbound but was already read on the phone.
  312. Caveats:
  313. - **The marker only moves forward.** Marking an already-read chat as *unread*
  314. again on the phone is not reflected.
  315. - **No marker means no read was ever reported** — for a chat with an inbound
  316. last message, `unread` then falls back to the old heuristic and reports
  317. true. Stores written by a bridge older than the `chats.last_read_time`
  318. column report `last_read_time: null` and behave the same way.
  319. - **`unread` is a chat-level flag, not an unread count.** WhatsApp's unread
  320. counter is not persisted.
  321. #### `list_chats`
  322. List all chats with metadata.
  323. **Parameters:**
  324. - `limit` (optional): Number of chats (default 50, max 200)
  325. #### `get_chat`
  326. Get specific chat metadata by JID.
  327. **Parameters:**
  328. - `jid` (required): Chat JID
  329. #### `get_direct_chat_by_contact`
  330. Find a direct message chat with a contact.
  331. **Parameters:**
  332. - `phone` (required): Phone number of the contact
  333. #### `get_contact_chats`
  334. List all chats involving a specific contact.
  335. **Parameters:**
  336. - `phone` (required): Phone number of the contact
  337. #### `get_last_interaction`
  338. Get the last message exchanged with a contact.
  339. **Parameters:**
  340. - `phone` (required): Phone number of the contact
  341. #### `get_message_context`
  342. Get messages around a specific message for context.
  343. **Parameters:**
  344. - `message_id` (required): ID of the target message
  345. - `chat_jid` (required): JID of the chat
  346. - `before` (optional): Number of messages before (default 5)
  347. - `after` (optional): Number of messages after (default 5)
  348. ## Configuration
  349. Copy `.env.example` to `.env` and configure as needed:
  350. | Variable | Default | Description |
  351. | ---------------------- | ---------------------------------------- | -------------------------------------------- |
  352. | `WHATSAPP_BRIDGE_PORT` | `8080` | Port for Go bridge REST API |
  353. | `WEBHOOK_URL` | `http://localhost:8769/whatsapp/webhook` | Webhook for incoming messages |
  354. | `WEBHOOK_ENABLED` | `true` | Set to `false` to disable outbound webhooks |
  355. | `FORWARD_SELF` | `true` | Forward messages sent by self |
  356. | `WHATSAPP_DB_PATH` | `../whatsapp-bridge/store/messages.db` | Path to SQLite database |
  357. | `WHATSMEOW_DB_PATH` | `../whatsapp-bridge/store/whatsapp.db` | whatsmeow DB used for LID ↔ phone resolution |
  358. | `WHATSAPP_API_URL` | `http://localhost:8080/api` | Go bridge REST API URL |
  359. | `WHATSAPP_BRIDGE_TOKEN` | generated next to `WHATSMEOW_DB_PATH` as `.bridge-token` | Bearer token for bridge REST calls; also signed onto outbound webhook POSTs |
  360. | `WHATSAPP_MEDIA_ROOTS` | `~/.local/share/whatsapp-mcp/outbox` | Path-list of directories allowed for outbound media files |
  361. | `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) |
  362. | `WHATSAPP_MCP_TRANSPORT` | `stdio` | MCP transport to serve clients: `stdio`, `http`, or `sse` |
  363. | `WHATSAPP_MCP_HOST` | `127.0.0.1` | Bind address for the `http`/`sse` transports |
  364. | `WHATSAPP_MCP_PORT` | `8000` | Port for the `http`/`sse` transports |
  365. | `WHATSAPP_PARENT_WATCHDOG_S` | `30` | Stdio parent-liveness poll interval (seconds); exits on parent reparent only |
  366. ### MCP transport (stdio vs http/sse)
  367. By default the server speaks MCP over **stdio**, which is what local clients
  368. like Claude Desktop and Cursor launch. To serve the server over the network
  369. instead, set `WHATSAPP_MCP_TRANSPORT`:
  370. ```bash
  371. # Streamable HTTP (current spec transport for remote MCP), endpoint at /mcp
  372. WHATSAPP_MCP_TRANSPORT=http WHATSAPP_MCP_PORT=8000 uv run main.py
  373. # Legacy Server-Sent Events transport (deprecated in the MCP spec), endpoint at /sse
  374. WHATSAPP_MCP_TRANSPORT=sse uv run main.py
  375. ```
  376. `http` is an alias for the spec's `streamable-http` transport and is the
  377. recommended choice for remote connections; `sse` is kept for older clients.
  378. > **Security:** `WHATSAPP_MCP_HOST` defaults to `127.0.0.1`, so the HTTP/SSE
  379. > server is reachable only from the local machine. The server has no built-in
  380. > authentication, and the underlying bridge can read and send WhatsApp messages
  381. > on your account. Only bind to a non-loopback address (e.g. `0.0.0.0`) if you
  382. > place an authenticating reverse proxy or tunnel in front of it.
  383. ### Bridge authentication and media paths
  384. The bridge requires bearer-token authentication for every `/api/*` request and
  385. accepts only exact loopback Host headers for its configured port. This protects
  386. the local REST API from other local processes and browser DNS-rebinding attacks.
  387. On first start, the bridge generates a 256-bit token, writes it to
  388. `.bridge-token` in the active bridge store directory with owner-only
  389. permissions, and prints a setup banner. The MCP server reads
  390. `WHATSAPP_BRIDGE_TOKEN` first, then falls back to `.bridge-token` in the same
  391. directory as `WHATSMEOW_DB_PATH`. For split deployments, containers, or process
  392. managers that do not share the store directory, set the same
  393. `WHATSAPP_BRIDGE_TOKEN` value for both the bridge and MCP server.
  394. The bridge also signs its **outbound** webhook POSTs (to `WEBHOOK_URL`) with this
  395. same token, sent as an `X-Bridge-Token: <token>` header — a dedicated header
  396. rather than `Authorization`, so it never collides with a receiver's own
  397. Authorization-based auth (e.g. HTTP Basic auth embedded in `WEBHOOK_URL` as
  398. `http://user:pass@host/...`, which `net/http` applies automatically as long as
  399. the bridge doesn't set its own `Authorization` header). The header is attached only when a token is configured **and** `WEBHOOK_URL` was
  400. explicitly set — never to the built-in local default. The bridge token also
  401. authorizes `/api/*` calls like sending messages, and nothing has vetted the
  402. implicit default address, so it must never be handed to whatever process
  403. happens to be listening there. Upgrades that predate the token rollout, or
  404. that never set `WEBHOOK_URL`, keep working unchanged. The webhook client also
  405. never follows redirects, so a misconfigured or malicious endpoint can't
  406. redirect the bridge into leaking the token to a different host. If your
  407. webhook receiver enforces the token, set its copy to this exact value: e.g.
  408. the AutoHub hub's `WHATSAPP_BRIDGE_TOKEN` must equal this bridge's token (from
  409. `.bridge-token` or its own env) — the hub accepts it via `X-Bridge-Token` or
  410. `Authorization: Bearer`. The bridge always sends the token it has; the hub
  411. rejects unauthenticated forwards only once its `WHATSAPP_BRIDGE_TOKEN` is set
  412. to the matching value.
  413. Outbound `media_path` values are confined to `WHATSAPP_MEDIA_ROOTS`. The default
  414. outbox is `~/.local/share/whatsapp-mcp/outbox`, created on bridge startup. Move
  415. files there before calling `send_file`, `send_audio_message` or
  416. `set_group_picture(image_path=...)`, or set
  417. `WHATSAPP_MEDIA_ROOTS` to a colon-separated list of absolute directories.
  418. ### Run automatically on macOS
  419. macOS users can install optional per-user `launchd` jobs that start the Go
  420. bridge at login and monitor it every 60 seconds for API health, disconnects, and
  421. QR relink signals. The installer does not require `sudo` and does not install or
  422. start the MCP server.
  423. ```bash
  424. scripts/install-launchd-macos.sh
  425. ```
  426. The installer builds `whatsapp-bridge/whatsapp-bridge` with `go build` when Go is
  427. available, writes generated support files to
  428. `~/Library/Application Support/whatsapp-mcp/`, writes LaunchAgents to
  429. `~/Library/LaunchAgents/`, and writes logs to `~/Library/Logs/whatsapp-mcp/`.
  430. It safely reloads only these labels:
  431. - `com.whatsapp-mcp.bridge`
  432. - `com.whatsapp-mcp.bridge-monitor`
  433. To customize the launchd environment, export values before running the installer.
  434. Re-run the installer after changing them.
  435. ```bash
  436. export WHATSAPP_BRIDGE_PORT=8080
  437. export WEBHOOK_URL=http://localhost:8769/whatsapp/webhook
  438. export FORWARD_SELF=false
  439. export WHATSAPP_MEDIA_ROOTS="$HOME/.local/share/whatsapp-mcp/outbox"
  440. scripts/install-launchd-macos.sh
  441. ```
  442. Verify the jobs and inspect logs:
  443. ```bash
  444. launchctl print gui/$(id -u)/com.whatsapp-mcp.bridge
  445. launchctl print gui/$(id -u)/com.whatsapp-mcp.bridge-monitor
  446. tail -n 100 ~/Library/Logs/whatsapp-mcp/bridge.err.log
  447. tail -n 100 ~/Library/Logs/whatsapp-mcp/monitor.err.log
  448. ```
  449. The monitor sends a macOS notification once per failure type until recovery. It
  450. alerts when the bridge LaunchAgent is unloaded, the token is missing, the health
  451. endpoint is unreachable, WhatsApp is disconnected, or recent logs indicate that
  452. QR relinking is needed.
  453. Uninstall the generated LaunchAgents and support files with:
  454. ```bash
  455. scripts/uninstall-launchd-macos.sh
  456. ```
  457. Uninstall preserves `whatsapp-bridge/store/`, including WhatsApp session DBs,
  458. message DBs, media, and `.bridge-token`. Logs are left in
  459. `~/Library/Logs/whatsapp-mcp/` for manual cleanup.
  460. ### CLI flags (Go bridge)
  461. | Flag | Default | Description |
  462. | --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  463. | `--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. |
  464. ### Requesting full history
  465. 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:
  466. ```bash
  467. # Stop the bridge
  468. launchctl bootout gui/$UID/com.whatsapp-mcp.bridge # or however you manage it
  469. # Back up, then remove the auth session (keeps messages.db intact)
  470. cp whatsapp-bridge/store/whatsapp.db{,.bak}
  471. rm whatsapp-bridge/store/whatsapp.db
  472. # Re-pair with the flag
  473. cd whatsapp-bridge
  474. ./whatsapp-bridge --full-history-pair
  475. # Scan the QR with WhatsApp → Settings → Linked Devices → Link a Device
  476. # Wait for "History sync complete" in the logs (can take 10-30 minutes)
  477. # Ctrl+C when sync has quiesced, then restart under your normal process manager
  478. ```
  479. Caveats:
  480. - **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.
  481. - **Only effective on a fresh pair.** With `whatsapp.db` already present, no new pair handshake fires and the flag is a no-op.
  482. - **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.
  483. ### Requesting history for a single chat (on-demand)
  484. `--full-history-pair` only applies to a fresh pair, so recovering a gap in one
  485. chat otherwise means deleting `whatsapp.db` and re-syncing everything. To ask
  486. the phone for older messages in a single chat *without* re-pairing:
  487. ```bash
  488. curl -X POST http://127.0.0.1:8080/api/history \
  489. -H "Authorization: Bearer $(cat whatsapp-bridge/store/.bridge-token)" \
  490. -H "Content-Type: application/json" \
  491. -d '{"chat_jid": "1234567890@s.whatsapp.net", "count": 50}'
  492. ```
  493. The request is anchored on the **oldest message already stored** for that chat,
  494. so the phone returns messages from before it. Call it repeatedly to page
  495. further back. Results arrive asynchronously through the normal history-sync
  496. handler and land in `messages.db` — typically within a few seconds.
  497. | Field | Required | Description |
  498. | --------- | -------- | ------------------------------------------------------ |
  499. | `chat_jid` | yes | Chat to backfill (`...@s.whatsapp.net` or `...@g.us`) |
  500. | `count` | no | Messages to request; default `50`, capped at `500` |
  501. Caveats:
  502. - **The phone decides how much it returns**, exactly as with pair-time sync, so
  503. `count` is a request rather than a guarantee.
  504. - **At least one message for the chat must already be stored**, since it is used
  505. as the anchor. Chats with no local messages return `404`; send or receive one
  506. message first.
  507. - Messages the phone has deleted are not recoverable, as above.
  508. ## Call History
  509. The bridge captures incoming WhatsApp voice and video calls live into a
  510. dedicated `calls` table in `messages.db`. When a 1:1 call arrives
  511. (`CallOffer`) or a group call is announced (`CallOfferNotice`), a row is
  512. inserted with `result='in_progress'`. Subsequent `CallAccept` /
  513. `CallReject` / `CallTerminate` events update the row — final result becomes
  514. `answered`, `rejected`, `missed`, or `ended` depending on the event
  515. sequence. See the state-machine comment above `StoreCallOffer` in `main.go`
  516. for the exact transitions.
  517. ### Schema
  518. ```sql
  519. CREATE TABLE calls (
  520. call_id TEXT,
  521. chat_jid TEXT, -- group JID for group calls, call creator JID for 1:1
  522. from_jid TEXT, -- JID of whoever started the call
  523. timestamp TIMESTAMP, -- call start time
  524. is_from_me BOOLEAN,
  525. call_type TEXT, -- 'voice' or 'video'
  526. is_group BOOLEAN,
  527. result TEXT, -- 'in_progress' | 'answered' | 'ended' |
  528. -- 'missed' | 'rejected'
  529. duration_sec INTEGER, -- computed when the call terminates
  530. ended_at TIMESTAMP,
  531. reason TEXT, -- terminate reason string from whatsmeow
  532. PRIMARY KEY (call_id, chat_jid)
  533. );
  534. ```
  535. ### Caveats
  536. - **Outbound calls are not captured.** WhatsApp's primary device handles
  537. calls it initiates without notifying linked devices, so the bridge never
  538. sees an event for them.
  539. - **Call results only reflect what the bridge saw.** If the bridge is
  540. offline when a call happens, the events are lost.
  541. - **1:1 calls default to `call_type='voice'`.** `CallOffer` events don't
  542. expose media type directly (it's buried in the binary call data). Group
  543. calls via `CallOfferNotice` include a `Media` field and are recorded
  544. accurately as voice or video.
  545. ## Architecture
  546. ```mermaid
  547. flowchart TB
  548. subgraph Clients["AI Clients"]
  549. CD[Claude Desktop]
  550. CU[Cursor IDE]
  551. CC[Claude Code]
  552. end
  553. subgraph MCP["MCP Layer"]
  554. PY[Python MCP Server<br/>FastMCP]
  555. end
  556. subgraph Bridge["WhatsApp Bridge"]
  557. GO[Go Bridge<br/>whatsmeow]
  558. DB[(SQLite<br/>messages.db)]
  559. WH[Webhook Handler]
  560. end
  561. subgraph External["External Services"]
  562. WA[WhatsApp Web API]
  563. EXT[External Webhook<br/>Receiver]
  564. end
  565. CD & CU & CC -->|MCP Protocol| PY
  566. PY -->|REST API| GO
  567. PY -->|Read| DB
  568. GO -->|Store| DB
  569. GO <-->|WebSocket| WA
  570. GO -->|Forward Messages| WH
  571. WH -->|POST| EXT
  572. ```
  573. ### Component Details
  574. ```mermaid
  575. flowchart LR
  576. subgraph GoAPI["Go Bridge REST API"]
  577. direction TB
  578. SEND["/api/send"]
  579. READ["/api/mark-read"]
  580. DOWN["/api/download"]
  581. REACT["/api/react"]
  582. TYPE["/api/typing"]
  583. HIST["/api/history"]
  584. HEALTH["/api/health"]
  585. end
  586. subgraph MCPTools["MCP Tools (15 total)"]
  587. direction TB
  588. CONT["Contact Tools<br/>search_contacts, get_contact"]
  589. MSG["Message Tools<br/>list_messages, send_message, etc."]
  590. CHAT["Chat Tools<br/>list_chats, get_chat, etc."]
  591. MEDIA["Media Tools<br/>send_file, download_media, etc."]
  592. end
  593. MCPTools -->|HTTP Requests| GoAPI
  594. ```
  595. ### Data Flow
  596. ```mermaid
  597. sequenceDiagram
  598. participant User as User
  599. participant Claude as Claude Desktop
  600. participant MCP as Python MCP Server
  601. participant Bridge as Go Bridge
  602. participant WA as WhatsApp
  603. User->>Claude: "Send 'Hello' to Mom"
  604. Claude->>MCP: send_message(recipient, message)
  605. MCP->>Bridge: POST /api/send
  606. Bridge->>WA: Send via WebSocket
  607. WA-->>Bridge: Delivery confirmation
  608. Bridge-->>MCP: Success response
  609. MCP-->>Claude: Message sent
  610. Claude-->>User: "Message sent to Mom"
  611. ```
  612. ### Incoming Message Flow
  613. ```mermaid
  614. sequenceDiagram
  615. participant WA as WhatsApp
  616. participant Bridge as Go Bridge
  617. participant DB as SQLite
  618. participant WH as Webhook
  619. participant EXT as External Service
  620. WA->>Bridge: New message
  621. Bridge->>DB: Store message
  622. Bridge->>Bridge: Auto-download media
  623. Bridge->>WH: Forward to webhook
  624. WH->>EXT: POST with message data
  625. Note over EXT: Process incoming message
  626. ```
  627. ## Development
  628. ### Running Tests
  629. ```bash
  630. cd whatsapp-mcp-server
  631. uv pip install -e ".[dev]"
  632. uv run pytest -v
  633. ```
  634. ### Linting
  635. ```bash
  636. # Python
  637. cd whatsapp-mcp-server
  638. uv run ruff check .
  639. uv run ruff format .
  640. # Go
  641. cd whatsapp-bridge
  642. golangci-lint run
  643. ```
  644. ### Building
  645. ```bash
  646. # Go bridge
  647. cd whatsapp-bridge
  648. go build -o whatsapp-bridge
  649. # Run the binary
  650. ./whatsapp-bridge
  651. # During development (avoids stale binaries)
  652. go run .
  653. ```
  654. ### Releasing (Maintainers)
  655. Releases use Release Please automation; maintainer steps and fallback procedures
  656. are documented in [docs/RELEASING.md](docs/RELEASING.md).
  657. ## Troubleshooting
  658. ### Authentication Issues
  659. - **Pairing fails with `Client outdated` or HTTP 405**: Update to the latest
  660. release and rebuild the bridge. WhatsApp periodically raises the minimum
  661. supported linked-device client version, which can make older whatsmeow builds
  662. fail before pairing completes.
  663. - **QR Code Not Displaying**: Restart the bridge. Check terminal QR code support.
  664. - **Device Limit Reached**: Remove a linked device from WhatsApp Settings > Linked Devices.
  665. - **No Messages Loading**: Initial sync can take several minutes for large chat histories.
  666. - **Out of Sync**: Back up `whatsapp-bridge/store`, then move
  667. `whatsapp-bridge/store/whatsapp.db` aside and re-authenticate. Keep
  668. `messages.db` unless you intentionally want to discard local message history.
  669. - **Bridge returns 401 Unauthorized**: Restart the bridge so it creates
  670. `.bridge-token` next to `WHATSMEOW_DB_PATH`, then restart the MCP server. If
  671. the MCP server cannot read that file, set `WHATSAPP_BRIDGE_TOKEN` to the same
  672. value in both environments.
  673. - **Bridge returns 403 Forbidden for Host**: Use `WHATSAPP_API_URL` with
  674. `http://127.0.0.1:<port>/api`, `http://localhost:<port>/api`, or
  675. `http://[::1]:<port>/api`; custom hostnames and missing ports are rejected.
  676. - **Bridge returns 403 Forbidden for media_path**: Move the file into
  677. `~/.local/share/whatsapp-mcp/outbox` or add its absolute parent directory to
  678. `WHATSAPP_MEDIA_ROOTS`.
  679. ### App State / LTHash Conflicts
  680. Some WhatsApp account state is managed by whatsmeow in
  681. `whatsapp-bridge/store/whatsapp.db`. If the bridge reports errors like:
  682. ```text
  683. SendAppState failed: server returned error updating app state (regular_low):
  684. <error code="409" text="conflict"/>
  685. failed to verify patch v12345: mismatching LTHash
  686. ```
  687. then WhatsApp's app-state patch chain for the linked device is out of sync.
  688. This usually affects operations that write chat settings such as archive,
  689. mute, or pin state. Incoming and outgoing messages may still work because
  690. message storage lives separately in `messages.db`.
  691. Known manual resync attempts such as `FetchAppState(..., fullSync=true)` may
  692. still fail on this upstream app-state error class. The practical recovery path
  693. is to reset the whatsmeow session and re-pair:
  694. ```bash
  695. # Stop the bridge first.
  696. launchctl bootout gui/$UID/com.whatsapp-mcp.bridge # or however you manage it
  697. # Back up the whole runtime store.
  698. cp -a whatsapp-bridge/store whatsapp-bridge/store.bak.$(date +%Y%m%d%H%M%S)
  699. # Reset only the whatsmeow session/app-state DB.
  700. mv whatsapp-bridge/store/whatsapp.db whatsapp-bridge/store/whatsapp.db.lthash.bak
  701. # Restart the bridge and scan the new QR code.
  702. cd whatsapp-bridge
  703. ./whatsapp-bridge # or `go run .` during development
  704. ```
  705. Do not remove `whatsapp-bridge/store/messages.db` for this recovery unless you
  706. also want to delete the local message archive.
  707. ### Windows
  708. Windows requires CGO for go-sqlite3. Install [MSYS2](https://www.msys2.org/) and enable CGO:
  709. ```bash
  710. go env -w CGO_ENABLED=1
  711. go run .
  712. ```
  713. ## Security Notice
  714. > **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.
  715. ## License
  716. MIT, see [LICENSE](LICENSE). Original work (c) 2025 Luke Harries; modifications (c) 2026 Very Good
  717. Plugins and, for qx-whatsapp-mcp, (c) 2026 Quinn Frederick. Unofficial; not affiliated with
  718. WhatsApp or Meta.
  719. ## Credits & History
  720. 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).
  721. **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.
  722. **Highlights since the fork:**
  723. - `/api/typing`, `/api/health`, and webhook forwarding (with reply context + image media)
  724. - Auto-download of incoming media with collision-safe filenames
  725. - `get_contact` tool, `sender_display` field, and LID ↔ phone resolution via the whatsmeow store
  726. - Live capture of incoming voice/video calls into a `calls` table
  727. - `--full-history-pair` flag to request extended history at pair time
  728. - Resilience: recovers from `StreamReplaced` session conflicts; pinned `anyio` to dodge a cancel-scope regression
  729. - CI/CD with GitHub Actions, Release Please for automated versioning, and Dependabot
  730. The full release-by-release list lives in [CHANGELOG.md](CHANGELOG.md).
  731. **Recent contributors** (huge thanks):
  732. - [@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)
  733. - [@davidsimoes](https://github.com/davidsimoes) — `StreamReplaced` recovery (#27)
  734. - [@davidggphy](https://github.com/davidggphy) — LID → phone JID consistency (#12)
  735. - [@maikol-solis](https://github.com/maikol-solis) — bridge run command fix (#23)
  736. - [@DeetBot](https://github.com/DeetBot) — `anyio` cancel-scope pin (#44)
  737. And to Luke for creating the original project. See [CONTRIBUTING.md](CONTRIBUTING.md) if you'd like to join in.
  738. ## Links
  739. - [Very Good Plugins](https://verygoodplugins.com/?utm_source=github)
  740. - [MCP Specification](https://modelcontextprotocol.io/)
  741. - [whatsmeow](https://github.com/tulir/whatsmeow) - WhatsApp Web API library for Go
  742. - [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.