Skip to main content
Glama

whatsapp-mcp

Give your AI agents your WhatsApp.

MCP server Runs on Cloudflare Workers License: GPL-3.0

Deploy to Cloudflare

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.

  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.

  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.

  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.

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 whatsapp

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, erase and webhooks.

Related MCP server: whatsapp-mcp

What your assistant can do

Tool

What it does

get_status

Connection state and how much of your history is saved

list_chats

Chats in the order your phone shows them, with unread counts

find_chats

Chats by any name or phone number

find_people

People by any name or phone, including group members

get_messages

A chat's messages, with voice messages transcribed

get_message_context

A message and the conversation around it

view_media

Shows an image, a video's preview or a voice message's text

search_messages

Search all chats by words, including transcribed voice messages

send_message

Sends text, as a reply or with mentions, never twice on retries

react_to_message

Adds or removes a reaction

edit_message

Edits a message you sent

delete_message

Deletes a message for everyone

mark_as_read

Marks a chat as read

save_contact

Saves or renames someone in your address book, on every device

remove_contact

Removes someone from your address book, on every device

load_older_messages

Asks your phone for older history

check_numbers

Which phone numbers have WhatsApp

get_group_info

A group's details and members

get_profile

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 /accounts/personal

What it does

GET /webhooks

Lists webhooks with their status and pending deliveries

POST /webhooks

Adds one and returns its secret

GET /webhooks/:id

One webhook and its last 50 deliveries

PATCH /webhooks/:id

Changes it; enabled pauses or resumes, rotate_secret too

DELETE /webhooks/:id

Deletes it and what it had pending

POST /webhooks/:id/test

Sends a webhook.test event now and reports how it went

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

Secret

The password of your server, at least 16 characters

AUTH_MODE

Variable

oauth (sign in through the browser), api_key (Bearer header) or both. both if unset

WEBHOOK_TOOLS

Variable

What MCP clients can do with webhooks: manage, read or off. manage if unset

TIMEZONE

Variable

Time zone for dates, like America/Sao_Paulo. UTC if unset

TRANSCRIBE_MODEL

Variable

@cf/openai/whisper-large-v3-turbo (default), @cf/deepgram/nova-3 or off

DESCRIBE_MODEL

Variable

@cf/mistralai/mistral-small-3.1-24b-instruct (default), @cf/meta/llama-4-scout-17b-16e-instruct or off

TRANSCRIBE_LANGUAGE

Variable

Language of most voice messages, like pt. Detected per message if empty

DESCRIBE_LANGUAGE

Variable

Language of image descriptions, like pt. English if empty

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 tests

To 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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Lets 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets 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 npm
      415
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Lets 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