javis-zalo

Zalo command-line tool and MCP server maintained for Javis OS. It signs into a personal Zalo account by QR code, then reads and sends messages, manages groups, notes, reminders and polls, either from the terminal or through the Model Context Protocol.

Unofficial API. Personal-account features talk to Zalo through zca-js, a reverse-engineered client. Zalo does not support this and the account may be restricted or locked. Read DISCLAIMER.md.

Install

Needs Node.js 20 or newer. Each release is a git tag, installed straight from GitHub (no npm account, no Git on the machine):

npm install -g https://codeload.github.com/blogminhquy/javis-zalo/tar.gz/refs/tags/v1.2.0

Or run once without installing:

npx -y https://codeload.github.com/blogminhquy/javis-zalo/tar.gz/refs/tags/v1.2.0 --help

The command is javis-zalo. The older name zalo-agent is kept as an alias.

Related MCP server: chatmux

Quick start

javis-zalo login                                  # prints a QR code; scan it in the Zalo app
javis-zalo conv recent                            # recent conversations
javis-zalo msg send <threadId> "Hello"            # 1:1 chat
javis-zalo msg send <threadId> "Hello" -t 1       # group
javis-zalo --json msg history <threadId> -t 1     # machine-readable output

Every command accepts --json. Run javis-zalo <group> --help for the full list (msg, friend, group, conv, account, profile, poll, reminder, label, catalog, listen, oa, mcp).

MCP server

javis-zalo mcp start                              # stdio, for an MCP client
javis-zalo mcp start --http 3847 --auth <token>   # HTTP, bound to 127.0.0.1

Tools: zalo_get_messages, zalo_get_history, zalo_search_history, zalo_list_threads, zalo_search_threads, zalo_view_media, zalo_get_group_joins, zalo_list_join_requests (read), zalo_mark_read (write), zalo_send_message (sends a message) and zalo_review_join_requests (approves or rejects people waiting to join a group; needs owner or deputy rights).

Group joins are recorded with their exact time while the server is connected and kept in ~/.zalo-agent-cli/group-joins.jsonl. Zalo's member list has no join date, so members who joined earlier, or while the server was offline, are not in it.

Where data lives

Sessions and settings stay on your machine under ~/.zalo-agent-cli/ (accounts, credentials, MCP config, downloaded media). Zalo Official Account credentials live in ~/.zalo-agent/. The folder names are kept from earlier builds so accounts that are already signed in stay signed in.

Nothing is sent anywhere except Zalo itself, a webhook or proxy you configure, and qr.sepay.vn when you ask for a bank-transfer QR image.

Development

npm ci
npm test
npm run lint
npm run format:check

See CONTRIBUTING.md and CHANGELOG.md.

License

MIT, see LICENSE.