whatsapp-mcp
Links to your WhatsApp account as a companion device (like WhatsApp Web) to give AI assistants read and write access to your chats. Provides tools to list and search chats, find people and groups, read messages with voice-note transcription, view media, get message context, and load older history, plus actions such as sending (idempotent) messages, reacting, editing and deleting messages, marking chats read, managing contacts, checking which numbers have WhatsApp, and fetching group and profile information. It also keeps a full-text searchable archive of the conversation history and can deliver incoming messages to user-configured webhooks.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
whatsapp-mcp
Give your AI agents your WhatsApp.
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 does, and keeps a searchable archive of your chats in your own Cloudflare account. It speaks MCP, so it works with Claude, ChatGPT, Claude Code, Cursor and other MCP clients.
Get started
You need a Cloudflare account on Workers Paid, a GitHub account and your phone.
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 forSECRET, give it a password of at least 16 characters, like the output ofopenssl rand -hex 32. Anyone who has it can read and send your messages.Open
https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal, sign in withSECRETand select Link WhatsApp. On your phone, go to Settings → Linked devices → Link a device and scan the code.personalis a name you choose, and each name is a separate WhatsApp account.Add
https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcpas 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 withSECRETand select Allow.
In Claude Code and pi:
claude mcp add --transport http whatsapp https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcp
pi mcp add whatsapp --url https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/mcp && pi mcp login whatsappClients 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, erase and webhooks.
Related MCP server: whatsapp-mcp
What your assistant can do
Tool | What it does |
| Connection state and how much of your history is saved |
| Chats in the order your phone shows them, with unread counts |
| Chats by any name or phone number |
| People by any name or phone, including group members |
| A chat's messages, with voice messages transcribed |
| A message and the conversation around it |
| Shows an image, a video's preview or a voice message's text |
| Search all chats by words, including transcribed voice messages |
| Sends text, as a reply or with mentions, never twice on retries |
| Adds or removes a reaction |
| Edits a message you sent |
| Deletes a message for everyone |
| Marks a chat as read |
| Saves or renames someone in your address book, on every device |
| Removes someone from your address book, on every device |
| Asks your phone for older history |
| Which phone numbers have WhatsApp |
| A group's details and members |
| Someone's name, About text and picture |
Tools that send or change something say so, and most assistants ask you before using them. Six more tools manage webhooks: list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook and test_webhook.
Webhooks
The server can POST every new message to your own URL as it arrives, for an n8n flow, a bot or an agent that answers on its own. Add one on the pairing page, ask your assistant, or call the API:
curl -X POST https://whatsapp-mcp.<your-name>.workers.dev/accounts/personal/webhooks \
-H "Authorization: Bearer $SECRET" \
-d '{"url": "https://example.com/whatsapp", "events": ["message.received"]}'The answer has the webhook's id and its signing secret, shown only this once. Each event arrives as its own request:
{
"id": "evt_6f1c0e2a9b8d4c3e8a7f5d1b2c3e4f50",
"type": "message.received",
"account": "personal",
"created_at": "2026-11-18T15:03:12.481Z",
"data": {
"chat": { "jid": "120363041234567890@g.us", "name": "Family", "type": "group" },
"message": {
"id": "3EB0C4F1A2B3C4D5E6F7",
"sent_at": "2026-11-18T15:03:11.000Z",
"from_me": false,
"sender": { "jid": "182736455463@lid", "name": "Marina", "phone": "+5511987654321" },
"kind": "text",
"text": "I'll be there at 7",
"reply_to": null
}
}
}The message, shortened here, has every field that get_messages shows, with null for the empty ones. The events are message.received, message.sent, message.edited, message.deleted, message.reaction and account.connection, which says when the number links, unlinks or is refused. A webhook can be limited to some events, to some chats (chats), to direct chats or groups (chat_types), send up to five fixed headers like Authorization (headers), and wait for voice messages to be transcribed (transcribe_voice).
Requests are signed with Standard Webhooks, so any of its libraries verifies them with the secret. A receiver that fails gets the event again after 5 seconds, then over about a day; webhook-id stays the same, so drop repeats by it. A receiver that answers 410 Gone, or fails for three days, is paused.
Method and path under | What it does |
| Lists webhooks with their status and pending deliveries |
| Adds one and returns its secret |
| One webhook and its last 50 deliveries |
| Changes it; |
| Deletes it and what it had pending |
| Sends a |
A webhook copies every later message out of your account, so an assistant should create one only when you ask. The tools make clients ask you first, and WEBHOOK_TOOLS can turn them down to read or off. ADR 0004 explains how delivery works.
How it works
flowchart LR
agent["AI assistant"] -- "MCP + OAuth" --> worker["Worker"]
worker -- "RPC" --> account
subgraph account["Durable Object, one per WhatsApp account"]
socket["WhatsApp session<br/>whatsapp-rust in WASM"]
archive[("SQLite archive<br/>full-text search")]
socket --> archive
end
socket <-- "WebSocket" --> whatsapp["WhatsApp"]
account -- "voice messages, images" --> ai["Workers AI<br/>speech to text, vision"]Each account lives in its own Durable Object, a small server with its own SQLite database. Inside it runs baileyrs, a WhatsApp client built on whatsapp-rust. An alarm every 30 seconds keeps it connected, also after deploys.
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).
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. The archive keeps the text, so search finds it and nobody pays twice (ADR 0001, ADR 0002).
Configuration
Name | Kind | Purpose |
| Secret | The password of your server, at least 16 characters |
| Variable |
|
| Variable | What MCP clients can do with webhooks: |
| Variable | Time zone for dates, like |
| Variable |
|
| Variable |
|
| Variable | Language of most voice messages, like |
| Variable | Language of image descriptions, like |
Set them in wrangler.jsonc, or with --var NAME:value on wrangler deploy.
Costs
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 has the numbers.
Is it safe?
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.
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.
Development
You need Bun.
bun install
printf 'SECRET=%s\n' "$(openssl rand -hex 32)" > .dev.vars
bun run dev # http://localhost:8787/accounts/dev
bun run check # types, lint, format and testsTo deploy from your machine, run bunx wrangler secret put SECRET once and then bun run deploy.
Message rendering and identity rules follow mautrix-whatsapp. Licensed under GPL-3.0.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
WhatsApp for Claude, ChatGPT or any AI agent: search, reply and send. Personal or Business API.
Read, summarize and send your own WhatsApp messages from AI assistants (OAuth 2.1).
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Connect your own WhatsApp number to Cursor, Claude and ChatGPT: catch up, search, send replies.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceLets an AI assistant read, search, and send messages in your own chats by linking to your account as a companion device and keeping a searchable archive of the history. It exposes tools for chats, people, groups, contacts, reactions, and message actions over MCP, running in your own Cloudflare account so the data stays with you.GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to read, search, and send WhatsApp messages by linking to an account as a companion device, keeping a searchable archive of chats on the user's own Cloudflare deployment. It also exposes tools for managing contacts, groups, reactions, edits, deletions, and read status through the Model Context Protocol.49 npmGPL 3.0
- AlicenseNot gradedqualityBmaintenanceLets an AI agent search and read your own WhatsApp chats from a self-hosted Cloudflare Worker, with full-text search across all messages, per-chat paging, and the ability to save contact names for numbers that appear unnamed. It is read-only, so it can never send messages on your behalf.49 npm415MIT
- AlicenseNot gradedqualityNot gradedmaintenanceLets AI assistants read, search, and send WhatsApp messages by linking to an account as a linked device, keeping a searchable archive of chats. It exposes tools for listing and finding chats and contacts, paging through message history, and sending, reacting to, editing, deleting, and marking messages read.GPL 3.0