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
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.
What You'll Need
Set these up before or after installing:
Environment variable: RELAY_HOME
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 GitHubFrom the project's GitHub README.
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 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_messagealso accepts arequestId, 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=trueturns off every outgoing action, andALLOWED_CHATSlimits 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):
- generates strong random keys (32 bytes each, from
crypto.randomBytes), - asks for your relay and Cloudflare doorway URLs. Both are optional: press Enter to stay local-only,
- writes a private
.env(and, if you use them,relay-worker/.secrets.jsonandclaude-proxy/.secrets.jsonfor deploying), - 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), andlist_profilesshows what's linked. Withoutprofile, 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:
- Enter your full name, country, phone number (with its country code) and email.
- 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.
- 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_IDand*_CLIENT_SECRETfor each provider with the redirect URLhttp://localhost:8787/auth/callback/<google|microsoft|github|facebook>(or yourPUBLIC_URL).RELAY_ACCOUNTS_URL=offturns 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 aswhatsapp-<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 travels | Your name, country and phone number, the names of your WhatsApp profiles, and which AI apps you set up. |
| What never travels | Your 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=offdisables 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
| Platform | Mechanism | Template |
|---|---|---|
| macOS | launchd user agent | scripts/macos/whatsapp-relay.plist |
| Linux | systemd user service | scripts/linux/whatsapp-relay.service (sudo loginctl enable-linger $USER makes it start at boot without logging in) |
| Windows | Task Scheduler, at logon, no admin needed | scripts/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)
- Deploy the relay (free Worker + D1):
Runcd 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.devnpm run setupin the repo root and give it that address. It writesrelay-worker/.secrets.json; upload it withcd relay-worker && npx wrangler secret bulk .secrets.json. Later redeploys can usenpm run deploy, which does both. - Deploy the Claude doorway (free):
Itscd claude-proxy npx wrangler login npm run deploy # wrangler deploy + upload .secrets.jsonwrangler.tomllinks it straight to thewhatsapp-relayWorker 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 resultinghttps://whatsapp-claude.<you>.workers.devaddress asCLAUDE_DOORWAY_URLin.env, then runnpm run setup -- --print. - 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).
| Setup | Requests/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
| Tool | Access | What 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.
| Variable | Default | Purpose |
|---|---|---|
HOST / PORT | 127.0.0.1 / 8787 | Where the local bridge listens |
BRIDGE_TOKEN | generated | Owner token for local MCP clients, and a recovery sign-in for the dashboard (β₯ 32 characters) |
RELAY_ACCOUNTS_URL | https://relay-accounts.viaan-mcp.workers.dev | Shared service that emails sign-in codes and runs the sign-in buttons; off disables it |
RELAY_ENCRYPTION | on | off stores data unencrypted (not recommended) |
RELAY_DATA_KEY | Keychain / key file | Your own 32-byte base64 data key instead of the system key store |
SMTP_URL / MAIL_FROM | unset | Your own email server for sign-in codes (used instead of the shared service) |
GOOGLE_/MICROSOFT_/GITHUB_/FACEBOOK_CLIENT_ID and _CLIENT_SECRET | unset | Your own OAuth apps for the sign-in buttons (used instead of the shared service) |
AUTO_CONNECT | true with npm run service | Reconnect a saved WhatsApp session on start |
READ_ONLY | false | Block every outgoing action, draft change and schedule |
ALLOWED_CHATS | all chats | Comma-separated chat JIDs the AI may access |
PUBLIC_URL | local | Public HTTPS origin if you expose the bridge directly (enables OAuth) |
RELAY_HOME | the clone, or ~/.relay-whatsapp-mcp for npm installs | Folder holding .env and data/ |
DATA_DIR | $RELAY_HOME/data | WhatsApp credentials, SQLite history, media cache |
RELAY_REMOTE_URL | none | Your relay's HTTPS origin (leave unset for local-only) |
RELAY_AGENT_KEY / RELAY_AGENT_ID | generated | Shared by your devices; the key also encrypts the relay queue |
RELAY_DEVICE_ID | generated | Unique per device; used for failover and read handoff |
RELAY_FAILOVER_ROLE | primary | Set standby on a second device |
RELAY_WATCH_MS | 750 | Standby only: how often to check the primary (3000 for the free tier) |
RELAY_SITE_KEY | none | Optional 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.
| Symptom | Fix |
|---|---|
Node.js 22.13 or newer is required | Install 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 Unauthorized | The x-api-key header doesn't match PROXY_KEY. Run npm run setup -- --print and paste the key again. |
Claude connector: 404 from the doorway | The 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 configured | Upload the doorway secrets: cd claude-proxy && npx wrangler secret bulk .secrets.json. |
| "Your Mac bridge is offline" from the relay | No 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 connected | Two 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 seconds | Harmless 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 use | Set 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:
| Check | Result |
|---|---|
Wrong x-api-key | rejected (401) |
initialize, tools/list | 38 tools |
Tool call round trip (status, list_chats, send_message, search_messages) | ~0.4β0.8 s each |
Same send_message requestId sent twice | one 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 failover | exactly one message |
| macOS launchd auto-start | starts; 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!
More Communication MCP Servers
Toleno
Freeby Toleno Β· Developer Tools
Toleno Network MCP Server β Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace Β· Developer Tools
Search and install MCP servers from inside your AI client.
mcp-creator-python
Freeby mcp-marketplace Β· Developer Tools
Create, build, and publish Python MCP servers to PyPI β conversationally.
by Lharries Β· Communication
Read, search, and send WhatsApp messages through your AI assistant
FinAgent
Freeby mcp-marketplace Β· Finance
Free stock data and market news for any MCP-compatible AI assistant.
Memory
Freeby Modelcontextprotocol Β· Productivity
Knowledge graph-based persistent memory across sessions
