Skip to main content
Glama
Zalo Read-only MCP

Zalo Read-only MCP

README.md
# Zalo Read-only MCP

**English** | [简体中文](README.zh-CN.md)

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](https://github.com/RFS-ADRENO/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):

```sh
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.

## Login

```sh
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

```sh
zalo-readonly config
```

This prints MCP configuration using absolute executable paths, without changing client settings. Typical configuration:

```json
{"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](docs/MUSE.md).

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 |

```sh
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:

```sh
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](docs/WEB-HISTORY.md).

## 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](docs/HISTORY.md).

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

```sh
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

```sh
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](docs/SECURITY.md), [protocol](docs/PROTOCOL.md), and [release notes](docs/RELEASING.md).

## License

Public source with personal/internal installation and use permission under [LICENSE](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.