zalo

claude-plugin-zalo

A Claude Code MCP plugin that bridges Zalo into your Claude sessions. Messages from approved senders appear live in your interactive session as channel events, and Claude replies under your own identity — this is your personal Zalo account, driven over a WebSocket by zca-js, not a bot.

Features

• Live channel events — no polling; allowed senders' messages render in the session as they arrive
• Background daemon — a single detached process owns the Zalo connection (spawn-on-demand; no console window, no scheduled task, nothing installed), so opening/closing Claude sessions never drops the connection
• Logs every message to SQLite — every inbound message is persisted to a canonical SQLite log, independent of whether a session is open
• Answers only when @mentioned — DMs and group @mentions wake the LLM; unmentioned group messages are logged silently (no reply, no LLM)
• Multi-session safe — N Claude sessions coexist; exactly one answers each message (atomic claim), none fight over the account
• Pairing-code access control — strangers get a code; you approve with /zalo:access pair <code>
• Allowlist lockdown — dmPolicy: allowlist silently drops anyone you haven't approved
• Reply, react, and durable attachments — chunked text replies, emoji/reaction codes, and inbound photo/file download that survives daemon restarts
• Permission relay — Claude Code permission prompts are forwarded to your DM; reply yes <id> / no <id>

Prerequisites

• Bun ≥ 1.2 — must be on your PATH; works on Windows, Linux, and macOS
• A Zalo personal account

Install

# Add the plugin source (one-time)
claude plugin marketplace add imrim12/claude-plugin-zalo

# Install
claude plugin install zalo@imrim12

Verify it loaded:

claude plugin list   # should show: zalo  ✔ loaded

The MCP server runs straight from npm via bunx claude-plugin-zalo — Bun fetches the package and its dependencies on first launch and caches them, so there's no manual install step and nothing OS-specific to configure. State lives under your home directory (~/.claude/channels/zalo), resolved cross-platform, independent of where Claude Code is launched from.

Enable inbound delivery (required)

Claude Code only renders notifications/claude/channel events from plugins on Anthropic's approved channels allowlist. This plugin is not on it, so inbound messages are silently dropped unless you launch the session with the development-channels flag:

claude --dangerously-load-development-channels plugin:zalo@imrim12

# Or YOLO mode

claude --dangerously-load-development-channels plugin:zalo@imrim12 --dangerously-skip-permissions

A confirmation dialog appears at startup — accept it. Without this flag, everything else still works (QR login, pairing auto-replies, outbound reply), which makes the failure look like a plugin bug: the sender sees the typing indicator but the message never reaches your session.

To confirm you're hitting this, check the newest file in Claude Code's MCP log directory for your project (%LOCALAPPDATA%\claude-cli-nodejs\Cache\<project>\mcp-logs-plugin-zalo-zalo\ on Windows) for:

Channel notifications skipped: plugin zalo@imrim12 is not on the approved channels allowlist

Quick start

1. Log in (personal account)

1. Run /zalo:auth (or call the zalo_login tool).
2. Scan the QR code at the path /zalo:auth reports (qr-login.png in the state directory) with the Zalo mobile app (More → QR scan).
3. Confirm on your phone. Credentials are saved automatically — no re-scan needed on restart.

2. Pair your other account

The default DM policy is pairing: when an unknown sender DMs your account, the plugin auto-replies with a 6-character code. Approve them in your terminal:

/zalo:access pair <code>

They get a "Paired!" DM, and from then on their messages appear live in your session (provided inbound delivery is enabled — see above).

Talk to the assistant from your own account: /self

Zalo has no chat-with-yourself, so you can't normally trigger the assistant from your own logged-in session. Send a message — in any chat — that starts with /self and the rest is fed to the assistant, which answers in that same chat:

/self summarize the unread messages in this group

Only messages you send yourself that begin with /self are picked up (every other self message is ignored). The chat you use is auto-allowlisted so the reply can go through, so prefer a group or a dedicated chat.

3. Lock it down

Once everyone you want is paired, switch to a hard allowlist so strangers are dropped silently:

/zalo:access policy allowlist

Manage everything else with /zalo:access — allow <id>, remove <id>, deny <code>, group add <threadId> [--no-mention] [--allow id1,id2], group rm <threadId>.

MCP tools