Best for
- Individuals who want to talk to Claude from their personal WhatsApp number
- Developers comfortable configuring from a terminal and using the Claude Code development flag
- Automation scenarios needing remote tool approval from a phone
W
WhatsApp Channel for Claude Code
Community
Drive your Claude Code session straight from WhatsApp
GitHub source repository ↗
64FMRS · C
A community-built WhatsApp channel plugin, reviewed and published to the Anthropic Official Plugin Marketplace (the repo describes it as the first community WhatsApp channel plugin reviewed and published by Anthropic). It links a personal WhatsApp account as a linked device with no API keys, Docker, or WhatsApp Business API. It is most complete inside Claude Code, where inbound messages can wake the session as channel notifications; on other MCP clients it degrades to polling. It suits individual developers who are fine configuring from a terminal and value local privacy, but not teams needing official hosting, multiple instances, or a compliance-grade enterprise channel. Note that only one linked session per account is allowed, and approval commands stay terminal-only by design for safety.
WhatsApp Channel for Claude Code is an MCP server that connects to WhatsApp as a linked device (the same protocol as WhatsApp Web, via Baileys) and exposes it to Claude Code as a channel. Incoming messages reach the session in real time, and Claude replies from your own number so recipients see a normal chat. Everything runs locally on your machine; messages travel directly between WhatsApp and your session with no third-party servers in between. Once paired it keeps working while your phone is off — only the Claude Code session needs to stay open, and reconnects never require re-pairing. It is a plain stdio MCP server any MCP client can run, though inbound waking relies on the Claude Code notifications/claude/channel extension; elsewhere it is poll-based.
Tools
reply
Send a message to a chat, with chunking and optional @-mentions.
react
Add an emoji reaction to a message (also used for permission approve/deny).
edit_message
Edit a previously sent message.
download_attachment
Download a received media attachment.
status
Report server and connection status.
unreplied
List unreplied messages and their count.
catch_up
Replay recent two-way conversation, unreplied counts, and open tasks after a restart.
list_groups
List available groups.
wait_for_messages
Poll for the next message, waiting up to about 40 seconds.
whatsapp_unavailable
The single tool served when another process holds the connection, naming the process that holds it.
Setup
Option 1 (Claude Code plugin): run claude plugin marketplace add Rich627/whatsapp-claude-plugin, then claude plugin install whatsapp-channel@whatsapp-claude-plugin, then launch with claude --dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin (this flag registers the plugin as a channel; without it tools load but new messages do not wake the session). Inside the session run /whatsapp-channel:configure <phone> (country code + number, no +); a pairing code is printed on first launch. On your phone: WhatsApp → Settings → Linked Devices → Link a Device → Link with phone number instead → enter the code. Option 2 (other MCP clients): register the stdio server with an absolute path, e.g. Codex CLI's ~/.codex/config.toml, Gemini CLI's ~/.gemini/settings.json, or Cursor's mcp.json, using command bun and args run --cwd /absolute/path/to/whatsapp-channel start, with generous timeouts (e.g. startup_timeout_sec 30, tool_timeout_sec 120).
claude_desktop_config.json
{
"mcpServers": {
"whatsapp": {
"type": "stdio",
"command": "bun",
"args": ["run", "--cwd", "/absolute/path/to/whatsapp-channel", "start"]
}
}
}
Fit and risk
Not for
- Compliance scenarios requiring the official WhatsApp Business API or a Meta developer account
- Teams needing officially hosted, multi-tenant, or cloud multi-instance deployment
- Environments unable to guarantee only one client instance at a time
- Users expecting voice transcription without setting up mlx-whisper themselves
Required permissions
- Read and send WhatsApp messages as your personal number
- Access the local runtime state directory ~/.whatsapp-channel/ (auth, allowlists, group configs, inbox)
- Read and write local repository files and run scripts (e.g. bun scripts/access.ts, scripts/watchdog.sh)
- Optional local voice transcription (ffmpeg and an mlx-whisper environment)
Risks and side effects
- Messages Claude sends appear from your own number and are indistinguishable to recipients
- WhatsApp allows one linked-device session per account; running two servers makes them kick each other off
- Access-control commands are deliberately not MCP tools (terminal-only); exposing them to the message side risks prompt injection
- Session waking depends on the Claude Code channel extension; other clients get no push
- A known Claude Code client bug (#37933) may cause messages not to arrive, a client-side issue
- Launching with --dangerously-load-development-channels carries risk, so verify the source is trustworthy
Troubleshooting
- Pairing code not showing: run /whatsapp-channel:configure <phone> first, then relaunch
- 440 disconnect error: only one connection per auth state is allowed; kill stale processes with pkill -f "whatsapp.*server"
- Session not waking on new messages: usually launched without --dangerously-load-development-channels plugin:whatsapp-channel@whatsapp-claude-plugin; check the MCP debug log for Channel notifications skipped
- Messages not arriving: may relate to Claude Code client bug #37933; server-side is correct
- Replies send but nothing arrives: send a DM as well as a group message; check ~/.whatsapp-channel/diag.log for inbound upsert lines and set WHATSAPP_DIAG_DEBUG=1 for Baileys' full debug stream
- Auth expired: run /whatsapp-channel:configure reset-auth and re-pair
- No push in other clients: poll with wait_for_messages, catch_up, or unreplied
Use cases
Drive a Claude Code session with natural language from WhatsApp
Transcribe incoming voice notes and hand the text to Claude
Approve or deny Claude's tool calls from a phone via emoji reaction
Give each group its own personality and conversation memory
Schedule recurring server-side tasks in a group's config.md
Gate incoming messages with pairing codes and allowlists
Supported clients
Claude CodeFull support
Codex CLIPartial support
Gemini CLIPartial support
CursorPartial support