Skip to main content
Glama
Zalo Read-only MCP

Zalo Read-only MCP

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.0

Install 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 status

login 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 config

This 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

zalo_sync_status

Progress of an explicitly started phone sync

zalo_status

Live process/connection state and cache coverage

zalo_conversations

Conversations present in this cache

zalo_web_status

Validate the explicitly attached browser/account

zalo_web_conversations

Conversations already stored in Zalo Web

zalo_web_history

Decoded per-conversation Zalo Web history with pagination

zalo_history

A bounded cached history page for one conversation

zalo_search

Cached text; not a server-wide search

zalo_events

Incremental locally stored records after a sequence cursor

zalo_coverage

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 coverage

10001 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-cancel

Confirm 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-mobile uses transfer-sync-v2 on 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 daemon
  • Default: $XDG_DATA_HOME/zalo-readonly-mcp or ~/.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; resume explicitly 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.1 on 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-run

Offline 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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