Back to Browse

Relay Whatsapp MCP Server

CommunicationLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Your WhatsApp as 38 MCP tools: read, search, send and media across accounts, self-hosted.

About

Your WhatsApp as 38 MCP tools: read, search, send and media across accounts, self-hosted.

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.

8 files analyzed Β· 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

Shell Command Execution

Runs commands on your machine. Be cautious β€” only use if you trust this plugin.

HTTP Network Access

Connects to external APIs or services over the internet.

What You'll Need

Set these up before or after installing:

Folder with Relay's .env and WhatsApp session (default: ~/.relay-whatsapp-mcp). Run `npx relay-whatsapp-mcp setup` and `start` first.Optional

Environment variable: RELAY_HOME

Address of the running Relay bridge (default: http://127.0.0.1:8787)Optional

Environment variable: BRIDGE_URL

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "relay-whatsapp-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "relay-whatsapp-mcp@1.2.0"
      ],
      "env": {
        "BRIDGE_URL": "your-bridge-url-here",
        "RELAY_HOME": "your-relay-home-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

Relay

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

CI License: MIT Node.js β‰₯ 22.13 Platforms MCP tools Security policy npm

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 and can be wrong. If Gemini isn't available, 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.


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.

  • Who can create an account: a local bridge only allows sign-up from the computer it runs on. A hosted bridge (PUBLIC_URL) also asks for the owner token, so a stranger can't claim it.
  • 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. Unless you turn on account sync (below), it stores no accounts and your account 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 to an account only if it's linked to that 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.

Several accounts on one computer

One computer can hold up to five Relay accounts, for example Business and Private. Each account has its own WhatsApp profiles, messages, encryption key, owner token and AI-app approvals, in its own folder (data/accounts/<id>/; the first account keeps using data/). Nothing in one account can be read from another.

  • Add one: in the dashboard's account menu (bottom left) choose Use another account…, then sign in or Create another account. Each account needs its own email.
  • Switch: pick the account in the same menu. A browser can stay signed in to several accounts; Sign out signs out of the one in front.
  • Claude: Add to Claude Desktop adds the account in front. The first account appears in Claude as whatsapp, and further ones as whatsapp-<email>, so Claude can use both and you can say which one you mean.
  • ChatGPT and other OAuth clients: an approval belongs to the account that was in front when you approved it, and the client reaches only that account's WhatsApp.
  • Remove one: Connections β†’ This account β†’ Remove this account from this computer (asks for its password). The first account can't be removed this way.
  • The optional Cloudflare relay (Use it from anywhere) serves the first account only.

Use an account on another computer (optional)

Off by default. In Connections β†’ Use this account on other computers, enter your password and the 6-digit code Relay emails you. After that, signing in to Relay on another computer with the same email and password brings the account there.

What travelsYour name, country and phone number, the names of your WhatsApp profiles, and which AI apps you set up.
What never travelsYour password, the WhatsApp link itself, messages, contacts, media, and AI-app tokens.
  • Each computer links WhatsApp once. WhatsApp's link can't be copied between computers (copying it breaks the link on both), so the new computer shows a short checklist: scan a QR code for each profile, and click Add to Claude Desktop again. ChatGPT connectors live in your ChatGPT account and point at one bridge's address, so they don't move by themselves.
  • The service can't read it. Relay makes two keys from your password on your computer. One proves who you are to the Relay Accounts service, which keeps only a hash of it. The other encrypts the synced copy and never leaves your computers. See SECURITY.md for the limits of this.
  • Changes to profile names travel both ways. A profile removed on one computer stays linked on the others until you remove it there too.
  • Password changes: resetting your password on a computer that has the account re-locks the synced copy with the new password. If you forget the password and no computer still has the account, the synced copy can't be opened; turn sync on again from a new account with the same email to replace it.
  • Turning it off deletes the service's copy. RELAY_ACCOUNTS_URL=off disables it, and when it is off or you have no account on this computer with the email you typed, a failed sign-in is all that happens.
  • When this is available, signing in with an email that has no account on this computer asks the service whether a synced account exists for it. That request carries the email address and a key derived from the password you typed, never the password.

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
PlatformMechanismTemplate
macOSlaunchd user agentscripts/macos/whatsapp-relay.plist
Linuxsystemd user servicescripts/linux/whatsapp-relay.service (sudo loginctl enable-linger $USER makes it start at boot without logging in)
WindowsTask Scheduler, at logon, no admin neededscripts/windows/install-autostart.ps1

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).

SetupRequests/day (approx.)Fits the free tier?
One bridge, idle~37,000 (one 2-second long poll at a time)βœ…
Primary + standby, default RELAY_WATCH_MS=750~37,000 + ~115,000❌ over the request limit
Primary + standby, RELAY_WATCH_MS=3000 on the standby~37,000 + ~29,000βœ… (failover takes ~7–9 s instead of ~4–6 s)

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

ToolAccessWhat it does
Chats and messages
status🟒Connection state, live event cursor, counts and capabilities
list_chats🟒Chats with names, unread counts, previews and exact chat IDs (JIDs)
list_contacts🟒Search contact names and WhatsApp IDs
get_messages🟒Read messages newest first, with pagination; never sends read receipts
search_messages🟒Literal text search across one chat or every permitted chat
wait_updates🟒Live messages, edits, receipts, reactions and presence after a durable cursor
export_chat🟒Export a page of history as JSON or plain text
Sending and changing messages
send_message🟑Send a text or reply; requestId de-duplicates retries
edit_messageπŸ”΄Edit your own text message (WhatsApp time limits apply)
delete_messageπŸ”΄Delete your own message for everyone
react_message🟑Add or remove an emoji reaction
forward_message🟑Forward a message to another permitted chat
create_poll🟑Create a poll
mark_read🟑Send read receipts for specific messages, only when you ask
Media
list_media🟒Find photos, videos, voice notes, stickers and documents in history
download_media🟒Download an attachment up to 500 MB (inline if small, otherwise a file handle)
read_media🟒Inspect an attachment as a native image, audio or document, or as a file handle
read_media_chunk🟒Read a cached attachment in bounded chunks
media_capabilities🟒Check local transcription, PDF, video-frame and vision support
analyze_media🟒Start a local analysis job: transcription, text extraction or visual description
get_media_analysis🟒Job status and paginated results
cancel_media_analysisβšͺCancel a queued or running analysis job
delete_cached_mediaβšͺRemove a cached download or upload (doesn't touch WhatsApp)
create_media_upload🟑Start a chunked upload for sending a file up to 500 MB
upload_media_chunk🟑Append up to 1 MB to an upload (safe to retry at the same offset)
send_media🟑Send an image, video, audio or document
Groups, presence and chat settings
get_group🟒Group subject, description, participants and roles
update_groupπŸ”΄Change a group's subject or description
set_presence🟑Online/offline, typing or recording indicators
subscribe_presence🟒Receive a chat's typing and presence events through wait_updates
set_chat_settings🟑Archive/unarchive, mute/unmute
Drafts and scheduling
save_draft🟑Save or update a local draft without sending
list_drafts🟒List drafts
delete_draftπŸ”΄Delete a draft
schedule_message🟑Schedule a text for an ISO 8601 time; interrupted sends become uncertain, never re-sent
list_scheduled🟒Scheduled messages and their delivery status
cancel_scheduledπŸ”΄Cancel a pending scheduled message

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.

VariableDefaultPurpose
HOST / PORT127.0.0.1 / 8787Where the local bridge listens
BRIDGE_TOKENgeneratedOwner token for local MCP clients, and a recovery sign-in for the dashboard (β‰₯ 32 characters)
RELAY_ACCOUNTS_URLhttps://relay-accounts.viaan-mcp.workers.devShared service that emails sign-in codes and runs the sign-in buttons; off disables it
RELAY_ENCRYPTIONonoff stores data unencrypted (not recommended)
RELAY_DATA_KEYKeychain / key fileYour own 32-byte base64 data key instead of the system key store
SMTP_URL / MAIL_FROMunsetYour own email server for sign-in codes (used instead of the shared service)
GOOGLE_/MICROSOFT_/GITHUB_/FACEBOOK_CLIENT_ID and _CLIENT_SECRETunsetYour own OAuth apps for the sign-in buttons (used instead of the shared service)
AUTO_CONNECTtrue with npm run serviceReconnect a saved WhatsApp session on start
READ_ONLYfalseBlock every outgoing action, draft change and schedule
ALLOWED_CHATSall chatsComma-separated chat JIDs the AI may access
PUBLIC_URLlocalPublic HTTPS origin if you expose the bridge directly (enables OAuth)
RELAY_HOMEthe clone, or ~/.relay-whatsapp-mcp for npm installsFolder holding .env and data/
DATA_DIR$RELAY_HOME/dataWhatsApp credentials, SQLite history, media cache
RELAY_REMOTE_URLnoneYour relay's HTTPS origin (leave unset for local-only)
RELAY_AGENT_KEY / RELAY_AGENT_IDgeneratedShared by your devices; the key also encrypts the relay queue
RELAY_DEVICE_IDgeneratedUnique per device; used for failover and read handoff
RELAY_FAILOVER_ROLEprimarySet standby on a second device
RELAY_WATCH_MS750Standby only: how often to check the primary (3000 for the free tier)
RELAY_SITE_KEYnoneOptional bearer credential if your relay sits behind an extra access layer

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.

SymptomFix
Node.js 22.13 or newer is requiredInstall the current LTS from nodejs.org; check with node --version.
No QR code, or "session rejected"In the dashboard choose Retry pairing. On your phone, remove stale entries under Linked devices.
AI says "Start the WhatsApp bridge first"The local MCP adapter talks to the running bridge: run npm start or npm run service.
Claude connector: 401 UnauthorizedThe x-api-key header doesn't match PROXY_KEY. Run npm run setup -- --print and paste the key again.
Claude connector: 404 from the doorwayThe doorway can't reach a relay on the same Cloudflare account by URL. Keep the [[services]] binding in claude-proxy/wrangler.toml pointing at your relay Worker's name.
Claude connector: 500 Forwarder is not configuredUpload the doorway secrets: cd claude-proxy && npx wrangler secret bulk .secrets.json.
"Your Mac bridge is offline" from the relayNo device has polled for 45 seconds. Check that npm run service is running and online, and that RELAY_* in .env match the relay's secrets.
409 Another Mac agent is already connectedTwo devices are using different RELAY_AGENT_IDs. A standby must reuse the primary's ID.
A send timed out and "may have executed"Intended behaviour: check the chat with get_messages before trying again. Relay never retries writes automatically.
Both devices answer for a few secondsHarmless overlap during failover; each request is still handled exactly once.
Auto-start doesn't start (macOS)launchctl print gui/$(id -u)/com.example.whatsapp-relay.service and data/service.log.
Auto-start doesn't start (Linux)systemctl --user status whatsapp-relay and journalctl --user -u whatsapp-relay.
Auto-start doesn't start (Windows)Task Scheduler β†’ WhatsApp Relay β†’ History, and data\service.log.
Port 8787 in useSet PORT=8789 in .env (and re-run npm run setup -- --print for new configs).

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:

CheckResult
Wrong x-api-keyrejected (401)
initialize, tools/list38 tools
Tool call round trip (status, list_chats, send_message, search_messages)~0.4–0.8 s each
Same send_message requestId sent twiceone message
Primary frozen (like a closed laptop lid)standby took over after 4.0 s and 5.3 s in two runs; a request already claimed by the frozen primary was handed over and answered in 5.8 s
Primary frozen partway through a read (wait_updates)read handed to the standby and answered; the late primary's result was refused (409)
A write after failoverexactly one message
macOS launchd auto-startstarts; a killed bridge restarts in ~2 s; a killed runner is restarted by launchd; uninstall removes everything

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.

Reviews

No reviews yet

Be the first to review this server!