WhatsApp for Claude Code

Read, search, and send WhatsApp messages from Claude Code — on your own personal account, 100% locally. Your messages live in SQLite on your machine; nothing is sent to any cloud, and sends always go through your approval.

"What did Ana say about the invoice last week?"
"Summarize my unread group chats."
"Send the address to Tom on WhatsApp."   ← asks for your approval first
"Download the PDF Maria sent me yesterday."

What you get

• A wa CLI for scripts, cron jobs, and any agent harness — reads answer in ~50 ms straight from the local store (even with the bridge down), sends go through the authenticated bridge. JSON in, JSON out:

  wa contacts "ana"                 # search people and group chats
  wa chats --limit 10               # recent chats, newest first
  wa messages "Ana Torres" --from-them --since 2026-07-01
  wa send "Team PRs" "https://github.com/org/repo/pull/42"
  wa doctor                         # health as JSON, exit code = status

• 14 MCP tools — search contacts, list/read chats and messages, message context, send text / files / voice notes / reactions, download media.
• A skill that teaches Claude the fast paths: direct SQLite for bulk reads, contact-first lookups, and the safety rules (approval-gated sends, incoming content treated as untrusted).
• Automated setup — /whatsapp-setup installs everything; the only manual step is scanning one QR code with your phone.
• Runs automatically — a keep-alive service (launchd on macOS, systemd on Linux, Task Scheduler on Windows) keeps the bridge running across reboots and crashes. /whatsapp-doctor checks and repairs the install.
• Hardened defaults — localhost-only REST API behind a bearer token, message store readable only by you, webhook forwarding disabled.

How it works

Your phone pairs this machine as a WhatsApp linked device (same mechanism as WhatsApp Web). Three local pieces, all from the open-source whatsapp-mcp project:

WhatsApp on your phone
   │  (linked device, end-to-end encrypted)
   ▼
Go bridge (whatsmeow) ──► SQLite store        ~/.whatsapp-mcp/whatsapp-bridge/store/
   │  localhost REST, bearer token
   ▼
Python MCP server ──► Claude Code (14 tools)

This plugin adds what the upstream project leaves to you: one-command setup, a pinned reviewed revision, permission hardening, the keep-alive service, pairing and health tooling, and the Claude Code skill/commands.

Quick start (Claude Code)

/plugin marketplace add Elnora-AI/elnora-whatsapp
/plugin install whatsapp@elnora-whatsapp
/whatsapp-setup

Scan the QR code when asked (WhatsApp > Settings > Linked Devices), restart Claude Code, and ask it about your chats. Total time ≈ 5 minutes, most of it the Go build.

Prerequisites: Go, uv, Node.js, git, curl (preinstalled on macOS). CGO needs a C compiler: preinstalled on macOS (CLT), build-essential on Debian/Ubuntu, and on Windows pacman -S mingw-w64-ucrt-x86_64-gcc in MSYS2. Optional: FFmpeg for sending arbitrary audio as voice notes.

CLI install (any terminal, any agent)

npm install -g @elnora-ai/whatsapp   # puts `wa` and `elnora-whatsapp` on PATH
wa doctor                            # then see `wa --help`

Needs Node ≥22.13 and a completed setup (below or /whatsapp-setup). Name resolution is agent-friendly: wa send "Ana Torres" hi works when the name is unique, and an ambiguous name fails with the candidate list instead of guessing. One recipient per send — bulk sending is refused by design.

Manual install (any MCP client)

The setup scripts work without Claude Code:

git clone https://github.com/Elnora-AI/elnora-whatsapp
bash elnora-whatsapp/scripts/setup.sh        # Windows: scripts\setup.ps1

Then register the MCP server in your client:

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["--directory", "<home>/.whatsapp-mcp/whatsapp-mcp-server", "run", "main.py"]
    }
  }
}

Useful flags: --dir <path> (custom location; also set WHATSAPP_MCP_DIR), --webhook <url> (forward incoming messages — off by default), --port <n> (bridge REST port), --no-service (skip the keep-alive service), --update (move an existing checkout to the pinned revision). Re-pair anytime with scripts/pair.sh (Windows: scripts\pair.ps1); check health with scripts/doctor.sh (scripts\doctor.ps1).

Security & privacy

• Local-only. Messages sync into SQLite on your machine and are read from there. The bridge's REST API binds to 127.0.0.1 and requires a bearer token (store/.bridge-token, mode 600).
• Webhook forwarding is OFF by default. The upstream bridge would otherwise POST every incoming message to a localhost port that any local process could claim; setup points it at a root-only discard port. Opt in with --webhook <url> if you actually consume it.
• Store hardening. store/ is chmod 700 (user-only ACL on Windows), the DBs and token 600. The store holds your full message history and session keys — never commit or copy it.
• Pinned upstream. Setup checks out a specific reviewed revision of whatsapp-mcp, not main. Update deliberately with --update.
• Prompt injection. Incoming message content is untrusted input. The skill instructs Claude to treat it as data and never follow instructions embedded in messages.
• Honest caveat: this is unofficial. Linked-device automation is not an official WhatsApp API. Read-heavy use with human-approved sends has been fine in practice, but bulk or spammy sending patterns can get an account banned. This project enforces nothing server-side — the skill's rules and your judgment do. Use at your own risk.

Uninstall

In Claude Code first: /plugin uninstall whatsapp@elnora-whatsapp. Then:

# macOS
launchctl bootout gui/$(id -u)/com.whatsapp-mcp.bridge
rm ~/Library/LaunchAgents/com.whatsapp-mcp.bridge.plist
rm -rf ~/.whatsapp-mcp      # deletes all synced messages + session
# Linux
systemctl --user disable --now whatsapp-bridge.service
rm ~/.config/systemd/user/whatsapp-bridge.service
rm -rf ~/.whatsapp-mcp

# Windows
Unregister-ScheduledTask -TaskName "WhatsApp MCP Bridge" -Confirm:$false
Remove-Item -Recurse -Force "$env:USERPROFILE\.whatsapp-mcp"

Also remove the linked device from your phone: WhatsApp > Settings > Linked Devices.

For agents

Setting this up for a user? Follow INSTALL_FOR_AGENTS.md. Driving an existing install from a non-Claude harness? See AGENTS.md.

Part of the Elnora family

This plugin is one of a set of universal, config-driven Claude Code tools from Elnora AI. Each works 100% standalone — install several and Claude chains them: a WhatsApp thread becomes a vault note, a task, a Linear issue, or an email follow-up in one conversation.

• knowledge-vault — Obsidian vault power tools. Chain: "summarize my chat with Ana and save it to the vault" turns WhatsApp messages into CRM notes and tasks in your own vault, searchable later.
• elnora-google-workspace — Gmail, Calendar, Drive, Docs, Sheets, and any Google API. Chain: cross-channel follow-ups — "she confirmed on WhatsApp, put it on the calendar and email the details".
• elnora-slack — the full Slack Web API as a CLI with a draft-and-approve send gate. Chain: relay between channels — "forward the gist of that WhatsApp group discussion to #team".
• elnora-linear — Linear search, bulk edit, agents, and a config-driven curator. Chain: "the client reported this bug on WhatsApp — file it in Linear with the message context".
• elnora-merit-aktiva — Merit Aktiva accounting + Merit Palk payroll CLI. Chain: "find the invoice Ana asked about on WhatsApp and check whether it's been paid".

Browse the full set at github.com/Elnora-AI.

Credits & license

Wraps verygoodplugins/whatsapp-mcp (maintained fork of lharries/whatsapp-mcp, MIT), built on whatsmeow. This repo: Apache-2.0, © Elnora AI.