whatsapp-bridge

A self-hosted bridge & seutp gateaway built on top of whats-meow for storing and accessing your raw whatsapp data

whatsapp-bridge links to your WhatsApp as an extra device, the way WhatsApp Web does. It keeps
the chats you choose in an encrypted database on your own VPS, where you can serach the chats or query them using MCP. It is read-only unless you turn on sending.

How it works

flowchart LR
    phone["Your phone<br/>(WhatsApp)"] -- "linked device,<br/>like WhatsApp Web" --> bridge["whatsapp-bridge<br/>on your server"]
    bridge --> db[("Encrypted database<br/>messages of ticked chats only")]
    ai["Your AI assistant<br/>Claude · ChatGPT · Codex"] -- "MCP, after you sign in<br/>read-only tools, sending opt-in" --> bridge

Link. On your phone, open Settings › Linked devices › Link a device and scan the
QR code. The bridge now receives your messages like any other linked device in WhatsApp.
Tick. Choose only which chats it keeps. Every chat starts unticked, and the bridge
stores none of its messages until you tick it. Tick within an hour of linking to also
keep the history WhatsApp sends at linking.
Ask. Connect your assistant to https://<your server>/mcp and sign in. It searches
and reads your ticked chats when it needs to, and cites every message it uses.

Try it locally

Go 1.27 or newer. The web UI is built into the binary.

git clone https://github.com/vid-t/whatsapp-bridge.git && cd whatsapp-bridge
CGO_ENABLED=0 go build -o bin/whatsapp-bridge ./cmd/whatsapp-bridge
./bin/whatsapp-bridge keygen > whatsapp-bridge.env && chmod 600 whatsapp-bridge.env
./bin/whatsapp-bridge serve -env-file whatsapp-bridge.env

Open http://127.0.0.1:8080, enter the access code from whatsapp-bridge.env, link
WhatsApp and tick your chats. Tick them within the hour to keep their recent history.

[!IMPORTANT]
whatsapp-bridge.env holds the database key. Without it the database cannot be read, so
back it up.

Run it on a server

claude.ai and ChatGPT reach the bridge from their own servers, so they need a public HTTPS
address. Claude Code and Codex also work over localhost or a private network.
deploy/SELF-HOSTING.md has three paths. Each ends at
https://<your domain> with automatic HTTPS from Caddy.

Path	Best for
A. cloud-init	a fresh VPS: paste one file and boot
B. Docker Compose	a server that already runs Docker
C. Install script	an existing Ubuntu 24.04 or Debian 12 server

You need a domain pointing at the server, with ports 80 and 443 open.

Connect your assistant

In Claude Code:

claude mcp add --transport http whatsapp-bridge https://<host>/mcp
claude mcp login whatsapp-bridge

In claude.ai, Claude Desktop, ChatGPT or Codex, add https://<host>/mcp as a connector and
sign in on the page that opens. docs/MCP-SETUP.md has the steps for
each assistant, plus API keys for scripts.

Your assistant gets six read-only tools:

Tool	What it does
`search_messages`	full-text search across the ticked chats
`read_chat`	read one chat in time order
`get_message_context`	show the messages around a search hit
`list_chats`	list the ticked chats, most recent first
`get_document`	give the file name and caption of an attachment
`get_status`	show the linked devices and how fresh the data is

Every message comes with a wa:// citation, so you can check the source of an answer.

Sending is off unless you turn it on. Set BRIDGE_ALLOW_SEND=1 and your assistant also
gets send_message, which sends a text message to one ticked chat from your account. It
cannot send to an unticked chat, and once you untick a chat nothing more can be sent to it.
Each assistant must also be allowed to send when you approve it. Assistants you approved
before stay read-only until you connect them again.
docs/CONFIGURATION.md has the details and limits.

Privacy and safety

Read-only unless you turn on sending. By default the bridge sends nothing. With
BRIDGE_ALLOW_SEND=1, assistants you allowed to send can send text messages, to ticked
chats only. It never
sends an "online" status or read receipts, and the tools cannot change or delete anything.
Only ticked chats. Chats start unticked. The bridge never stores the messages of an
unticked chat, only its name and last activity for the chat list, so no assistant can see
it. For an hour after you link a phone, it holds those messages in memory only, so a chat
you tick in that hour keeps its history. Then they are dropped.
Encrypted at rest. The database file is encrypted with Adiantum when BRIDGE_DB_KEY
is set (keygen creates it). A running bridge decrypts messages in memory, so run it on
a machine you control.
Closed by default. It listens on 127.0.0.1 and refuses a public address unless an
access code and a database key are set.
Audited. Every tool call is logged: who called it, which tool, which chats and how
many rows. The log never holds message text.
Nothing goes to an AI provider on its own. Your assistant gets messages only when it
calls a tool, and only that call's results.
Your phone stays in charge. Unlink the device in WhatsApp and the bridge is cut off
at once. WhatsApp also logs out linked devices when the phone has been offline for 14
days.

[!WARNING]
Unofficial client. whatsapp-bridge uses whatsmeow,
an unofficial implementation of the WhatsApp Web protocol. It is not affiliated with,
endorsed by or connected to WhatsApp or Meta. WhatsApp does not permit unofficial
clients, and an account linked to one can be restricted. Staying silent and read-only
keeps that risk low but cannot remove it, and turning on sending raises it: send what a
person would send, never bulk messages. You accept the risk when you link an account.

Not built yet: downloading attachments and reading their text, and limiting what each
member sees (today every member sees all ticked chats).

Documentation

Configuration and commands: every setting, flag and command
Self-hosting: install, upgrade and back up
Connect your assistant: Claude, ChatGPT, Codex and API keys
Security policy · Contributing

Licence

AGPL-3.0-only. If you run a modified whatsapp-bridge as a service, you must offer
its source code to the people who use it.