Relay

Your WhatsApp, as 38 MCP tools for Claude and ChatGPT: self-hosted, failover-ready, and free to run.

Ask your AI things like:

• "What did I miss in the family group today? Summarise it in three lines."

• "Find the address Sam sent me last month."

• "Transcribe the voice note from Priya and draft a reply. Don't send it yet."

• "Check my Work WhatsApp for anything urgent."

Why people use it: free and self-hosted, works with Claude and ChatGPT, several WhatsApp accounts in one place, nothing sent without you asking, and a standby that takes over in seconds if your computer sleeps.

💬 Ask Relay AI (Free Live Assistant): a help page with a searchable troubleshooting guide and an AI chat sidebar for questions about setup, failover, the 38 tools or security. It's free, with no login or key, and each visitor's chat stays private in their own browser. Answers come from these docs via Google Gemini (or Cloudflare Workers AI as a backup) and can be wrong. If the free daily AI allowance runs out, it answers from a docs search instead.

Quickstart with npx

Needs Node.js 22.13+. Nothing to clone:

npx relay-whatsapp-mcp

Your browser opens http://127.0.0.1:8787. Create your account (Google, GitHub, or email), click Connect WhatsApp, and scan the QR code from WhatsApp → Settings → Linked devices. Then open Connections and click Add to Claude Desktop (or Add to Claude Code), and restart Claude. That's it: from then on Claude starts Relay by itself when it needs it. The same from a terminal:

npx relay-whatsapp-mcp connect

Claude Code: claude mcp add whatsapp -- npx -y relay-whatsapp-mcp mcp. Claude Desktop, in claude_desktop_config.json:

{ "mcpServers": { "whatsapp": { "command": "npx", "args": ["-y", "relay-whatsapp-mcp", "mcp"] } } }

Try it without a WhatsApp account first: npx relay-whatsapp-mcp demo (sample chats). npx relay-whatsapp-mcp doctor checks everything; help lists all commands. Your private files (.env, the WhatsApp session, data) live in ~/.relay-whatsapp-mcp, never inside npm's folders; set RELAY_HOME to change that. If Claude Desktop reports that npx was not found, put the full path from which npx (where npx on Windows) in "command". To run Relay at login, install it permanently with npm install -g relay-whatsapp-mcp, then run relay-whatsapp-mcp autostart. The optional Cloudflare relay (Claude on your phone, failover) is deployed from a clone: see the 5-minute quickstart.

Relay links your own WhatsApp account as a linked device (like WhatsApp Web) on a computer you control and exposes it to AI assistants through the Model Context Protocol. Ask Claude to summarise a group chat, find the address a friend sent last month, transcribe a voice note, or draft and send a reply. It acts only when you ask it to.

   ┌──────────┐                 ┌──────────┐
   │ ChatGPT  │                 │  Claude  │   claude.ai · Desktop · Code · mobile
   └────┬─────┘                 └────┬─────┘
        │ owner sign-in               │ x-api-key
        │                    ┌────────▼──────────┐
        │                    │ Cloudflare doorway│  claude-proxy/ (free Worker)
        │                    └────────┬──────────┘
        │                             │ client key
   ┌────▼─────────────────────────────▼──────────┐
   │            Relay  (relay-worker/)            │  owner-only MCP endpoint
   │  queue encrypted at rest · AES-256-GCM       │  Worker + D1 (free tier)
   └───────────────┬────────────────┬─────────────┘
       outbound    │ long poll      │ long poll    outbound only:
       HTTPS only  │                │              no open ports at home
   ┌───────────────▼─────┐   ┌──────▼──────────────────┐
   │  Primary bridge     │   │  Standby bridge         │
   │  macOS·Linux·Windows│   │  macOS·Linux·Windows    │
   │  WhatsApp linked    │   │  (optional) its own     │
   │  device #1          │   │  linked device #2       │
   └─────────────────────┘   └─────────────────────────┘
         WhatsApp keys and message history never leave these machines

You don't need the hosted part: a single bridge with Claude Desktop or Claude Code on the same computer works with no hosting at all.

Related MCP server: W Agent

Why Relay

38 WhatsApp tools, not just "send a message"

Read and search history, follow live events with a durable cursor, download and analyse attachments up to 500 MB (local transcription, PDF/OCR, video frames, optional local vision), send and reply, edit, delete, react, forward, polls, drafts, scheduled messages, groups and presence. Full reference ↓

Failover in about 4–6 seconds, never sending twice

• Run an optional standby bridge on a second computer. If the primary sleeps or loses its connection, the standby starts serving after about 4–6 seconds of silence (about 7–9 s with the free-tier setting), then steps back when the primary returns.

• Reads in progress are handed over. If a device goes silent in the middle of a read-only request, the relay re-queues that request for the other device.

• Writes are never re-queued or retried automatically (send, edit, delete, react, groups and so on). Each queued request is claimed by exactly one device (an atomic UPDATE … WHERE status='queued'). A write that times out is reported as may have executed, with an instruction to check the chat instead of retrying. send_message also accepts a requestId, so a retry with the same ID is de-duplicated, and an interrupted scheduled send is marked uncertain rather than re-sent.

Built-in defences against indirect prompt injection

Incoming WhatsApp content is written by other people, so Relay treats it as data, never instructions:

• Every MCP server Relay exposes (local, remote and relay) carries server instructions saying that message text, attachments and contact names are untrusted and must not be followed as instructions.

• Attachment and analysis results are labelled as untrusted content.

• Writes happen only through explicit, schema-validated tool calls. READ_ONLY=true turns off every outgoing action, and ALLOWED_CHATS limits which chats the AI can see at all.

• Reading never sends read receipts, so an AI browsing your chats doesn't reveal that you've seen them.

These measures reduce the risk; they can't make a language model immune to manipulation. See SECURITY.md.

Cross-platform, runs on free tiers

• The bridge is plain Node.js, so it runs on macOS, Linux and Windows. It also runs on Android (Termux) as an experimental option.

• Auto-start templates for launchd, systemd and Task Scheduler, installed with one command.

• No AI API key, no subscription and no per-message fees. The relay and the Claude doorway both run on Cloudflare's free Workers and D1 plans. See free-tier budget for the numbers.

5-minute quickstart

You need: Node.js 22.13+ and WhatsApp on your phone.

git clone https://github.com/viaanshetty3-debug/relay-whatsapp-mcp.git && cd relay-whatsapp-mcp
npm install
npm run setup

npm run setup (macOS, Linux and Windows):

1. generates strong random keys (32 bytes each, from crypto.randomBytes),

2. asks for your relay and Cloudflare doorway URLs. Both are optional: press Enter to stay local-only,

3. writes a private .env (and, if you use them, relay-worker/.secrets.json and claude-proxy/.secrets.json for deploying),

4. prints ready-to-paste configs for Claude Desktop, Claude Code and ChatGPT.

Then link WhatsApp:

npm start

Open http://127.0.0.1:8787 and create your account (see Dashboard sign-in). Then choose Connect WhatsApp, and on your phone go to WhatsApp → Settings → Linked devices → Link a device and scan the QR code. Paste the printed config into your AI client and ask it:

Check my WhatsApp connection and list my 3 most recent chats. Don't send anything.

To see your configs again later: npm run setup -- --print. If anything seems off, run npm run doctor. In a few seconds it checks Node, your .env, the bridge and WhatsApp session, the relay and the Claude doorway, and says what to fix.

Several WhatsApp profiles

One Relay can hold up to 10 WhatsApp accounts, for example personal and work. In the dashboard, open the profile menu next to the connection status and choose ＋ Add another WhatsApp…, name it, and scan the QR code with that phone. Switch between profiles from the same menu, and use ⋯ to rename or remove one.

• Each profile is its own linked device with its own folder (data/profiles/<id>/): login, messages and media are never shared. The first profile ("Main") keeps the original data folder, so existing installs need no migration.

• One AI connection reaches all of them. Every tool takes an optional profile (a name or id), and list_profiles shows what's linked. Without profile, tools use Main. For example: "Check my Work WhatsApp for anything urgent."

• Removing a profile unlinks Relay from that WhatsApp account and deletes its synced data from this computer; the phone keeps everything. Main can be renamed but not removed.

Dashboard sign-in

The first time you open the dashboard, you create the bridge's owner account:

1. Enter your full name, country, phone number (with its country code) and email.

2. Choose a strong password: 12+ characters with upper and lower case, a number and a symbol. It can't contain your name or email, and the form shows each rule as you type.

3. Relay emails a 6-digit code to confirm your email. Enter it, and you're in.

After that you sign in with your email and password, or with Google, Microsoft, GitHub or Facebook if they're set up. Forgot password? emails a code to reset it.

• One owner per bridge: a bridge reads one WhatsApp account, so sign-up closes once the account exists. A local bridge only allows sign-up from the computer it runs on. A hosted bridge (PUBLIC_URL) also asks for the owner token once, so a stranger can't claim it first.

• Nothing to set up: codes are emailed, and the sign-in buttons run, through the shared Relay Accounts service (accounts-worker/, a Cloudflare Worker). It sees only the email address, the code and which provider you used, never your password, and it stores no accounts. The account itself lives only on your bridge. The service sends your bridge back a short-lived Ed25519-signed answer, which the bridge checks with a public key built into Relay. In demo mode, codes are shown on screen.

• Running it all yourself: set SMTP_URL (any SMTP server) to send codes yourself, and/or add your own *_CLIENT_ID and *_CLIENT_SECRET for each provider with the redirect URL http://localhost:8787/auth/callback/<google|microsoft|github|facebook> (or your PUBLIC_URL). RELAY_ACCOUNTS_URL=off turns the shared service off completely.

• Which sign-ins count: a provider signs you in only if it's linked to the owner account or reports the same verified email. Microsoft emails count as verified only for personal accounts.

• Security: passwords are stored with scrypt. Sessions are HttpOnly cookies that last 30 days, and resetting the password signs out every other session. Ten wrong passwords lock sign-in for 15 minutes, and five wrong codes void a code.

• The owner token still exists for local MCP clients and adapters, and as a recovery sign-in under Use the owner token instead. AI clients connecting with OAuth (such as ChatGPT) are approved by the signed-in account.

Keep it running

npm run service       # bridge (+ relay agent, if configured), restarts automatically if it crashes

Auto-start on login

npm run autostart                   # install and start
npm run autostart -- --dry-run      # preview what will be installed
npm run autostart -- --uninstall    # remove

Each template has instructions for installing it by hand at the top. Logs go to data/service.log on macOS and Windows, and journalctl --user -u whatsapp-relay on Linux.

Use it from anywhere (optional)

1. Deploy the relay (free Worker + D1):

   cd relay-worker
   npx wrangler login
   npx wrangler d1 create whatsapp-relay   # paste the printed database_id into wrangler.toml
   npx wrangler deploy                     # prints https://whatsapp-relay.<you>.workers.dev

   Run npm run setup in the repo root and give it that address. It writes relay-worker/.secrets.json; upload it with cd relay-worker && npx wrangler secret bulk .secrets.json. Later redeploys can use npm run deploy, which does both.

2. Deploy the Claude doorway (free):

   cd claude-proxy
   npx wrangler login
   npm run deploy        # wrangler deploy + upload .secrets.json

   Its wrangler.toml links it straight to the whatsapp-relay Worker with a service binding: Cloudflare doesn't let one Worker call another on the same account by its public URL. If your relay is hosted elsewhere, delete the [[services]] block. Add the resulting https://whatsapp-claude.<you>.workers.dev address as CLAUDE_DOORWAY_URL in .env, then run npm run setup -- --print.

3. In claude.ai → Settings → Connectors → Add custom connector, use the printed URL, choose No sign-in, and add the request header x-api-key.

ChatGPT: ChatGPT custom connectors can't send custom headers, so they can't use the relay's client key. Expose the bridge itself over HTTPS (PUBLIC_URL, for example with deploy/SELF-HOST.md) and connect ChatGPT with OAuth, which is built into the bridge.

Free-tier budget

Cloudflare's free plan currently allows 100,000 Worker requests and 100,000 D1 rows written per day (check Cloudflare's pricing for current limits).

Each poll also writes about two D1 rows (device liveness), so an always-on primary uses roughly 70% of the free daily writes. Tool calls add a few requests and writes each.

Add a standby later (24/7)

On a second computer: clone, npm install, npm run setup, and choose 2) standby. Paste RELAY_REMOTE_URL, RELAY_AGENT_KEY and RELAY_AGENT_ID from the primary's .env. Then npm start and link WhatsApp again on that machine, so it's a separate linked device. Never copy data/ between machines: two bridges sharing one WhatsApp session will break both. If your relay is on workers.dev, setup sets RELAY_WATCH_MS=3000 on the standby to stay within the free tier.

Tool reference

Access: 🟢 read-only · 🟡 write (changes WhatsApp or local state) · 🔴 destructive · ⚪ local cache only

The bridge also exposes the resource whatsapp://recent (recent permitted messages, labelled untrusted).

Configuration

npm run setup writes .env (in the clone, or in ~/.relay-whatsapp-mcp when installed from npm). Every value can also be set as a normal environment variable. See .env.example.

Relay secrets: WA_AGENT_KEY, WA_CLIENT_KEY (relay-worker/.env.example). Doorway secrets: RELAY_URL, PROXY_KEY, CLIENT_KEY, SITE_KEY (optional) (claude-proxy/.env.example).

Troubleshooting

Start with npm run doctor. It catches most of the problems below automatically.

Project layout

bin/              `relay-whatsapp-mcp` command for the npm package (setup, start, mcp, doctor, …)
src/              bridge: WhatsApp session (Baileys), SQLite store, MCP tools, dashboard API, remote agent
public/           dashboard (no build step, no external assets)
scripts/          setup helpers, service runner, auto-start installers (macos/, linux/, windows/)
relay-worker/     hosted relay: Cloudflare Worker + D1; src/lib/ holds the broker and encrypted queue protocol
claude-proxy/     Cloudflare Worker "doorway" for claude.ai custom connectors
docs-ai-worker/   "Relay Help": troubleshooting guide + Ask Relay AI sidebar on Cloudflare Workers AI
deploy/           Docker / self-hosting recipes (see deploy/SELF-HOST.md, deploy/HOSTING.md)
test/             Node test suite (+ Python tests for media and session transfer)
setup.mjs         `npm run setup`
server.json       MCP Registry metadata (must match package.json's version and mcpName)

Development

npm test                                    # bridge, relay broker, failover, setup, auto-start
(cd claude-proxy && npm test)               # doorway
(cd relay-worker && npm test)               # standalone relay
python3 -I -m unittest discover -s test     # optional media worker / transfer helpers

See CONTRIBUTING.md.

Verified end to end

Before release, the full path (a Claude-style MCP client → Cloudflare doorway → relay Worker + D1 on the free plan → two bridges in demo mode, primary and standby) was deployed with the commands in this README and tested live:

Linux (systemd) and Windows (Task Scheduler) auto-start are installed and checked for real on GitHub-hosted machines in CI.

Limits and honest caveats

• Relay uses Baileys, an unofficial WhatsApp Web client. WhatsApp changes can break it, and automated use can lead to account restrictions. Use it for your own account and normal conversations.

• Only history that WhatsApp syncs to the linked device is available.

• AI clients read live data when they call a tool. Relay doesn't make an idle conversation run on its own, and there are no automatic AI replies.

• WhatsApp credentials and message history are encrypted at rest with a per-device key kept in the Keychain (macOS) or a private key file in your user profile (Windows, Linux, Termux). This protects copies and backups of data/, not a machine someone is signed in to, and the media cache isn't encrypted yet. See SECURITY.md.

License

MIT. Dependencies keep their own licenses. WhatsApp is a trademark of WhatsApp LLC; Relay is not affiliated with or endorsed by WhatsApp, Meta, Anthropic or OpenAI.