Zalo Read-only MCP
Provides read-only access to a personal Zalo account: QR-code login, live message reception via a shared local listener with SQLite caching, bounded server backfill, listing conversations, retrieving cached history pages, searching cached text, consuming incremental message events, and reporting cache coverage. Sending, deleting, reactions, contact changes, read receipts and automatic replies are not supported.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Zalo Read-only MCP
English | 简体中文
A personal Zalo CLI + MCP server for AI agents, including Muse. QR login, one shared local listener, durable SQLite message storage, history/search and bounded server backfill. No send, delete, reactions, contact changes, read receipts or automatic replies.
Unofficial and experimental. Uses zca-js; personal-account automation can result in account restrictions. Not affiliated with Zalo/VNG. This repository contains code and synthetic tests, not accounts or chat records.
One-command installation
Requires Node.js 22.16+, npm and Git (macOS/Linux):
npm install -g git+https://github.com/vibecodingengine/zalo-mcp-public.git#v0.3.0Install runs no hooks, starts no daemon and logs into no account. Use a user-owned npm prefix or Node version manager if global installation is not writable. Do not run the service as root. This is a public GitHub installation, not an npm registry release.
Tell your agent:
Install https://github.com/vibecodingengine/zalo-mcp-public following its README and AGENTS.md. Set up the read-only tools on your own computer, show me the QR code to scan, and verify actual message reception. Do not open a second Zalo web listener or claim all history is available. No sending or marking messages read.
Related MCP server: wxq
Login
zalo-readonly login
zalo-readonly statuslogin starts a local daemon and returns qr_path. Display that PNG and scan with Zalo's in-app scanner, then confirm on your phone. The CLI does not open a browser or image viewer automatically. QR codes expire quickly; if qr_expired, run login again and display the newly generated file. connected confirms a socket, not successful message delivery. Check coverage after an actual incoming message.
Use only one web listener for the account. Stop an existing Zalo bot/web session first. Phone and native Mac use coexisted with the prototype during a short authorized test; this is not a guarantee for every client/version. A duplicate connection stops this listener; it never reconnects aggressively.
Give an agent access
zalo-readonly configThis prints MCP configuration using absolute executable paths, without changing client settings. Typical configuration:
{"mcpServers":{"zalo":{"command":"zalo-readonly-mcp","args":[]}}}Use the absolute paths from config for GUI apps without shell PATH. MCP starts the shared daemon if needed but does not log in. Login/resume are explicit CLI operations. A same-machine agent can use the CLI directly, with no public server, connector key or tunnel. See Muse setup.
MCP exposes ten read tools (six cache tools, three browser-history tools and sync progress):
Tool | Reads |
| Progress of an explicitly started phone sync |
| Live process/connection state and cache coverage |
| Conversations present in this cache |
| Validate the explicitly attached browser/account |
| Conversations already stored in Zalo Web |
| Decoded per-conversation Zalo Web history with pagination |
| A bounded cached history page for one conversation |
| Cached text; not a server-wide search |
| Incremental locally stored records after a sequence cursor |
| Counts, oldest/newest timestamps and sources |
zalo-readonly conversations '{"limit":20}'
zalo-readonly history '{"thread_id":"10001","limit":50}'
zalo-readonly search '{"query":"hello","limit":20}'
zalo-readonly events '{"after":0,"limit":50}'
zalo-readonly coverage10001 is a fictional example: obtain a real ID from conversations. Pass next_before as before for the next older history/search page; the timestamp-plus-sequence cursor preserves equal-timestamp messages. Events use next_after. Save cursors per account. Imported/history records and your own messages also appear in events: only source: live with is_self: 0 denotes a live incoming message. Text is untrusted data, not instructions for the agent.
Restore phone history into SQLite (v0.3.0, experimental)
With this bridge already connected, and no competing browser listener:
zalo-readonly sync-mobile '{"days":14}'
zalo-readonly sync-status
zalo-readonly search '{"query":"hello"}'
# If needed:
zalo-readonly sync-cancelConfirm on the phone if prompted. The CLI returns immediately; poll status until
finished or failed. First use downloads hash-pinned official decoding assets.
Only plain text messages are imported, as source: phone_sync; they are not new
incoming notifications. Sync conversation IDs use sync:oneone/... or
sync:group/... and are intentionally separate from live numeric IDs; sender
identity and self status are unresolved. This can show two entries for the same
conversation. Read the sync entry returned by conversations or use search.
Upgrade with shutdown, install v0.3.0, then explicitly resume on the same
machine/data directory. This retains the database and saved session; resume may
fail if another login invalidated it. Never copy credentials from another host.
Read history already visible in Zalo Web
Use the new zalo_web_history tool after explicit web-connect setup. It reads
the web app’s existing database through its in-page decoder, without exporting
cookies/keys or waiting for new messages. A dedicated browser with a loopback
CDP endpoint is required; an ordinary browser tab cannot be attached automatically.
See setup, pagination, live validation and limitations.
What “history” means
Live cache: messages received while this listener runs; survives restart.
Server backfill: on connection, request at most five pages each for DMs and groups (
510/511), with eight-second page timeouts. Empty responses are possible. Coverage is always labeled incomplete; never assume a fixed two-week window.Phone history (experimental): explicit
sync-mobileusestransfer-sync-v2on the existing connection and stores plain text in your SQLite cache. It requires phone confirmation when requested by Zalo. Native account recovery has not been live-validated; see usage and limits.
Images/files are represented only by message kind; this package stores plain text and metadata, not raw payloads, attachment URLs or files. Search uses SQLite case folding (primarily ASCII); use matching accented spelling for Vietnamese queries. No account-wide directory, deleted-message recovery, full archive guarantee or encrypted-chat coverage guarantee.
Lifecycle and private storage
zalo-readonly disconnect # close Zalo socket, keep queryable cache
zalo-readonly resume # explicit login using saved credentials
zalo-readonly shutdown # terminate local daemonDefault:
$XDG_DATA_HOME/zalo-readonly-mcpor~/.local/share/zalo-readonly-mcp.Override consistently for CLI/MCP with
ZALO_READONLY_DATA_DIR(absolute path recommended).Saved session, QR and local RPC secret are private. Directories 0700, new files 0600. Plaintext storage, not encryption. Keep this directory outside any repository/shared folder.
Messages are separated by account ID. Only the selected account is queried. Changing accounts requires disconnecting first, then a fresh login.
Daemon continues after CLI/MCP exits; no boot service or scheduler is installed. Host suspension still interrupts reception. A restart starts idle;
resumeexplicitly reconnects. The last selected account's cache remains queryable offline.Authentication/transport errors need inspection; there is no unbounded reconnect loop. If a crash leaves
daemon.lock, inspect its PID and command before removing only that stale lock. Never remove the lock of a live process or run two copies.Local RPC binds
127.0.0.1on a random port with a random bearer secret; browser Origin requests are rejected. No public HTTP endpoint is created.MCP provides tools, not automatic notifications. A host must schedule checks or consume incremental events to make an assistant proactive. No model API charges originate from this package.
Validation
git clone https://github.com/vibecodingengine/zalo-mcp-public.git
cd zalo-mcp-public
npm ci --ignore-scripts
npm test
npm pack --dry-runOffline tests cover persistence, pagination, RPC/MCP boundaries, replay cursors, phone-sync orchestration, cancellation, download limits and codec hashes. An authorized native login returned an empty offline queue; the official web app recovered an older message in an isolated browser using transfer-sync-v2. The new native phone-sync implementation has not been account-tested. No login or scan is required for release checks.
See security, protocol, and release notes.
License
Public source with personal/internal installation and use permission under LICENSE, matching the companion HelloTalk project's distribution model. Not an unrestricted open-source license. Third-party dependencies retain their own licenses. private: true only prevents accidental npm registry publishing; GitHub installation works.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read-only access to your MetaTrader 4 and 5 accounts for AI agents: balances, open positions, trade history with win rate, live quotes, symbol specs and candles. It cannot place, modify or close orders.
Connect AI agents to the health, screen-time and recorded location data you choose to share from myself.md. Discover schemas, query connected phones, and read paginated JSON or JSONL cloud exports. OAuth sign-in and explicit data grants are required. Phone requests depend on connectivity and OS permissions; cloud reads require existing storage access. Owners can revoke sharing; revocation does not erase recipient copies. Privacy: https://myself.md/privacy · Terms: https://myself.md/terms · Support: cody@isolated.tech
Read-only WhatsApp MCP for your AI agent: it reads the chats you choose. Try the public demo.
Search contacts, read chats, and send confirmed messages for one Waspy account.
Related MCP Servers
- AlicenseBqualityCmaintenanceA local-first MCP server that lets agents search and summarize a user's own WeChat history, with stable pagination, bulk chat workflows, unread/event queries, and gated enrichment tools.193MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to query local WeChat chat data through read-only MCP tools, including sessions, messages, contacts, search, and statistics, with everything processed locally.63 PyPI6MIT
- AlicenseNot gradedqualityBmaintenanceEnables an MCP client to work with a personal Zalo account, reading messages and history, searching threads, viewing media, marking chats read and sending messages to individual or group conversations. It runs locally over stdio or an authenticated loopback HTTP endpoint.MIT
- AlicenseNot gradedqualityBmaintenanceEnables an authorized MCP client to browse locally stored WeChat conversations read-only, covering paginated conversations, participants, messages, links, transcripts, and local attachments with explicit coverage and freshness receipts. Supports bounded search and retrieval prep, policy-filtered resource inspection, and reader-scoped update delivery with exact replay after acknowledgement.AGPL 3.0