Skip to content
Back to search

whatsapp-mcp

WhatsApp Unofficial MCP Server

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/felipeadeildo--whatsapp-mcp/badge.svg)](/listings/felipeadeildo--whatsapp-mcp)

HTML

<a href="/listings/felipeadeildo--whatsapp-mcp"><img src="/api/listings/felipeadeildo--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.25.5+** (for local setup) or **Docker** (recommended) - **WhatsApp account** (will be linked via QR code) - **MCP-compatible AI client** (Claude, Cursor, etc.)

Option 1: Docker Setup (Recommended)

1. **Clone and configure**

   git clone https://github.com/felipeadeildo/whatsapp-mcp
   cd whatsapp-mcp
   cp .env.example .env
   # Edit .env with your settings (API key, timezone, etc.)

2. **Start the server**

   docker compose up -d

3. **Link WhatsApp**

   # View logs to see QR code
   docker compose logs -f whatsapp-mcp

   # Scan QR code with WhatsApp mobile app:
   # Settings → Linked Devices → Link a Device

4. **Verify it's running**

   curl http://localhost:8080/health
   # Expected: "OK"

Option 2: Local Setup

1. **Install dependencies**

   git clone https://github.com/felipeadeildo/whatsapp-mcp
   cd whatsapp-mcp
   go mod download

2. **Configure environment**

   cp .env.example .env
   # Edit .env with your settings

3. **Run the server**

   go run main.go

4. **Link WhatsApp** (scan QR code shown in terminal)

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 · 136 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. <div align="center">
  2. # whatsapp-mcp
  3. **Give your AI agents your WhatsApp.**
  4. [![MCP server](https://img.shields.io/badge/MCP-server-3cc488?style=flat-square)](https://modelcontextprotocol.io) [![Runs on Cloudflare Workers](https://img.shields.io/badge/runs_on-Cloudflare_Workers-f38020?style=flat-square&logo=cloudflare&logoColor=white)](https://developers.cloudflare.com/durable-objects/) [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-8ba69d?style=flat-square)](LICENSE)
  5. [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/felipeadeildo/whatsapp-mcp)
  6. <br>
  7. <img src="docs/pairing.png" alt="Pairing page with a QR code inside a camera viewfinder and the three steps to link a device" width="820">
  8. </div>
  9. whatsapp-mcp lets an AI assistant like Claude read, search and send your WhatsApp messages. It links to your account as a device, the way [WhatsApp Web](https://faq.whatsapp.com/1317564962315842) does, and keeps a searchable archive of your chats in your own [Cloudflare](https://www.cloudflare.com) account. It speaks [MCP](https://modelcontextprotocol.io/introduction), so it works with Claude, ChatGPT, Claude Code, Cursor and other MCP clients.
  10. <div align="center">
  11. <img src="docs/use-cases.svg" alt="Three examples. You ask what Marina said about the trip, the assistant calls find_people and search_messages, and you get her message. You ask which chats are unread since yesterday, it calls list_chats, and you get Family, Book club and Marina with their counts. You ask it to tell the family group you'll be late, it calls find_chats and send_message, and the message is delivered once." width="820">
  12. </div>
  13. ## Get started
  14. You need a [Cloudflare account](https://dash.cloudflare.com/sign-up) on Workers Paid, a [GitHub account](https://github.com/signup) and your phone.
  15. 1. Click **Deploy to Cloudflare** above. Cloudflare copies this project to your GitHub and puts it online at `https://whatsapp-mcp.<your-name>.workers.dev`. When it asks for `SECRET`, give it a password of at least 16 characters, like the output of `openssl rand -hex 32`. Anyone who has it can read and send your messages.
  16. 2. Open `https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal`, sign in with `SECRET` and select **Link WhatsApp**. On your phone, go to **Settings → Linked devices → Link a device** and scan the code. `personal` is a name you choose, and each name is a separate WhatsApp account.
  17. 3. Add `https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcp` as a custom connector in Claude or ChatGPT, or as a remote MCP server in any other client. It opens your server in the browser, where you sign in with `SECRET` and select **Allow**.
  18. In Claude Code and [pi](https://pi.dev):
  19. ```sh
  20. claude mcp add --transport http whatsapp https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcp
  21. pi mcp add whatsapp --url https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcp && pi mcp login whatsapp
  22. ```
  23. Clients that can set a header can skip the browser and send `Authorization: Bearer <SECRET>`. Scripts can use the same header with the REST API under `/accounts/personal`: `status`, `start`, `send`, `logout` and `erase`.
  24. <div align="center">
  25. <img src="docs/linked.png" alt="Pairing page after linking, with the archive size and the MCP endpoint ready to copy" width="820">
  26. </div>
  27. ## What your assistant can do
  28. | Tool | What it does |
  29. | --------------------- | --------------------------------------------------------------- |
  30. | `get_status` | Connection state and how much of your history is saved |
  31. | `list_chats` | Chats in the order your phone shows them, with unread counts |
  32. | `find_chats` | Chats by any name or phone number |
  33. | `find_people` | People by any name or phone, including group members |
  34. | `get_messages` | A chat's messages, with voice messages transcribed |
  35. | `get_message_context` | A message and the conversation around it |
  36. | `view_media` | Shows an image, a video's preview or a voice message's text |
  37. | `search_messages` | Search all chats by words, including transcribed voice messages |
  38. | `send_message` | Sends text, as a reply or with mentions, never twice on retries |
  39. | `react_to_message` | Adds or removes a reaction |
  40. | `edit_message` | Edits a message you sent |
  41. | `delete_message` | Deletes a message for everyone |
  42. | `mark_as_read` | Marks a chat as read |
  43. | `save_contact` | Saves or renames someone in your address book, on every device |
  44. | `remove_contact` | Removes someone from your address book, on every device |
  45. | `load_older_messages` | Asks your phone for older history |
  46. | `check_numbers` | Which phone numbers have WhatsApp |
  47. | `get_group_info` | A group's details and members |
  48. | `get_profile` | Someone's name, About text and picture |
  49. Tools that send or change something say so, and most assistants ask you before using them.
  50. ## How it works
  51. ```mermaid
  52. flowchart LR
  53. agent["AI assistant"] -- "MCP + OAuth" --> worker["Worker"]
  54. worker -- "RPC" --> account
  55. subgraph account["Durable Object, one per WhatsApp account"]
  56. socket["WhatsApp session<br/>whatsapp-rust in WASM"]
  57. archive[("SQLite archive<br/>full-text search")]
  58. socket --> archive
  59. end
  60. socket <-- "WebSocket" --> whatsapp["WhatsApp"]
  61. account -- "voice messages, images" --> ai["Workers AI<br/>speech to text, vision"]
  62. ```
  63. Each account lives in its own [Durable Object](https://developers.cloudflare.com/durable-objects/), a small server with its own SQLite database. Inside it runs [baileyrs](https://github.com/oxidezap/baileyrs), a WhatsApp client built on [whatsapp-rust](https://github.com/oxidezap/whatsapp-rust). An alarm every 30 seconds keeps it connected, also after deploys.
  64. Your phone sends your recent history when you link, and the archive keeps every message after that, even the ones deleted for everyone, marked as deleted. If WhatsApp unlinks the device, link the same number again and the archive picks up where it stopped. Only **Erase the archive** on the pairing page deletes it ([ADR 0003](docs/adr/0003-archive-outlives-the-link.md)).
  65. The server transcribes a voice message the first time your assistant reads it, and describes an image the first time your assistant views it, both with [Workers AI](https://developers.cloudflare.com/workers-ai/). The archive keeps the text, so search finds it and nobody pays twice ([ADR 0001](docs/adr/0001-transcribe-on-read.md), [ADR 0002](docs/adr/0002-images-as-sent-described-on-view.md)).
  66. ## Configuration
  67. | Name | Kind | Purpose |
  68. | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
  69. | `SECRET` | Secret | The password of your server, at least 16 characters |
  70. | `AUTH_MODE` | Variable | `oauth` (sign in through the browser), `api_key` (Bearer header) or `both`. `both` if unset |
  71. | `TIMEZONE` | Variable | Time zone for dates, like `America/Sao_Paulo`. `UTC` if unset |
  72. | `TRANSCRIBE_MODEL` | Variable | `@cf/openai/whisper-large-v3-turbo` (default), `@cf/deepgram/nova-3` or `off` |
  73. | `DESCRIBE_MODEL` | Variable | `@cf/mistralai/mistral-small-3.1-24b-instruct` (default), `@cf/meta/llama-4-scout-17b-16e-instruct` or `off` |
  74. | `TRANSCRIBE_LANGUAGE` | Variable | Language of most voice messages, like `pt`. Detected per message if empty |
  75. | `DESCRIBE_LANGUAGE` | Variable | Language of image descriptions, like `pt`. English if empty |
  76. Set them in `wrangler.jsonc`, or with `--var NAME:value` on `wrangler deploy`.
  77. ## Costs
  78. One account costs $5 per month, the price of Workers Paid, and its included usage covers it. Transcribing a thousand voice messages adds about $0.26. Workers Free isn't enough: the first sync writes more rows than it allows in a day. [docs/costs.md](docs/costs.md) has the numbers.
  79. ## Is it safe?
  80. Your session and messages stay in your Cloudflare account. The server talks to WhatsApp, and to Workers AI for the voice messages and images your assistant opens. Without `SECRET`, nobody can use it or allow an app in. The server never opens view-once media.
  81. This is an unofficial WhatsApp client, not affiliated with WhatsApp or Meta, and WhatsApp can ban accounts that use one. Link a number you can afford to lose, and keep your assistant asking before it sends messages.
  82. ## Development
  83. You need [Bun](https://bun.sh).
  84. ```sh
  85. bun install
  86. printf 'SECRET=%s\n' "$(openssl rand -hex 32)" > .dev.vars
  87. bun run dev # http://localhost:8787/accounts/dev
  88. bun run check # types, lint, format and tests
  89. ```
  90. To deploy from your machine, run `bunx wrangler secret put SECRET` once and then `bun run deploy`.
  91. Message rendering and identity rules follow [mautrix-whatsapp](https://github.com/mautrix/whatsapp). Licensed under [GPL-3.0](LICENSE).
  92. <br>
  93. <div align="center">
  94. <a href="https://adeildo.dev"><img src="https://adeildo.dev/assets/images/cat.svg" width="44" alt="A cat asleep on a laptop, the adeildo.dev logo"></a>
  95. <br>
  96. <sub>Brought to you by <a href="https://adeildo.dev">adeildo.dev</a></sub>
  97. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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