zalo-mcp

Gói cài đặt độc lập Model Context Protocol (MCP) server và CLI wrapper cho Zalo. Cho phép cài đặt toàn cục qua npm hoặc triển khai trong môi trường đóng gói (sandbox) 1-click giúp AI agents (Claude Code, Cursor) tự động hóa Zalo Personal & Official Account mà không làm rác máy tính của bạn. Cả hai cách cài đặt đều cung cấp lệnh zalo-mcp trực tiếp trên terminal.

Tiếng Việt | English

[!TIP] Sự khác biệt giữa zalo-mcp và zalo-agent-cli?

• zalo-agent-cli: Là bộ mã nguồn lõi (engine). Xử lý toàn bộ logic API, login, và chứa mã nguồn thật sự của MCP Server.
• zalo-mcp (Repo này): Là vỏ bọc triển khai nhanh (deployment & CLI wrapper). Nó không chứa mã nguồn lõi mà chuyển tiếp toàn bộ lệnh CLI và khởi chạy MCP Server từ @ardennguyen/zalo-agent-cli. Dù bạn cài toàn cục (npm i -g @ardennguyen/zalo-mcp) hay dùng script 1-click tạo thư mục biệt lập (tự động npm link và cấu hình .env), bạn đều có thể chạy lệnh zalo-mcp ở bất kỳ đâu.

---

📋 Yêu cầu hệ thống

Trước khi cài đặt, hãy đảm bảo máy bạn đã có:

• Node.js: Phiên bản 22 trở lên (Bắt buộc cho MCP server và CLI).
• Git: Cần thiết để clone các bản cập nhật phụ thuộc.
• @ardennguyen/zalo-agent-cli: zalo-mcp 2.0.5 trở lên cần engine >=2.5.0 (gói tự cài đúng phiên bản). Engine 2.5.0 trở lên có đủ tool MCP mới nhất và các cờ --webhook / --webhook-secret; tool và cờ mới của engine chỉ dùng được qua zalo-mcp sau khi bạn cập nhật (.zalo-mcp.ps1 update / ./zalo-mcp.sh update, hoặc npm install -g @ardennguyen/zalo-mcp@latest nếu cài toàn cục). Engine 2.5.6 trở lên thêm webhook bền vững (mcp webhook status), /ready và /metrics, lệnh fleet cho nhiều tài khoản, và gửi tin Markdown thành định dạng thật của Zalo; mọi cờ và lệnh con này đi qua zalo-mcp như bình thường.

---

🚀 Bắt đầu nhanh

Bạn có thể chọn Cách 1 (Cài đặt toàn cục qua npm) hoặc Cách 2 (Cài đặt thư mục biệt lập 1 dòng lệnh). Cả hai cách đều đăng ký lệnh zalo-mcp vào PATH để bạn sử dụng ở mọi nơi.

Cách 1: Cài đặt toàn cục qua npm (Global CLI)

npm install -g @ardennguyen/zalo-mcp

Cách 2: Cài đặt thư mục cách ly (1 dòng lệnh)

Mọi phụ thuộc (dependencies) sẽ được tải vào một thư mục cách ly (zalo-mcp/), tạo file .env và tự động liên kết lệnh zalo-mcp toàn cục (npm link). Bạn có thể cài đặt ở bất kỳ đâu trên máy tính chỉ với 1 lệnh duy nhất:

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.sh | bash -s install

Windows (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.ps1 | Out-File $env:TEMP\zalo-mcp.ps1; & $env:TEMP\zalo-mcp.ps1 install

Trình cài đặt 1-click sẽ làm gì?

1. Tạo thư mục zalo-mcp tại vị trí hiện tại.
2. Tải các file wrapper và cấu hình.
3. Cài đặt các gói Node.js vào thư mục node_modules/ cục bộ.
4. Liên kết lệnh zalo-mcp toàn cục (npm link) để chạy từ mọi thư mục.
5. Tạo file cấu hình .env cho Port (ZALO_MCP_HTTP_PORT).

[!TIP] Phân tách file .env được khuyến nghị: Chỉ nên dùng zalo-mcp/.env để cấu hình PORT (ZALO_MCP_HTTP_PORT). Các biến môi trường điều hướng thư mục lưu trữ (ZALO_CREDENTIALS_DIR, ZALO_DATA_DIR, ZALO_MEDIA_DIR, ZALO_OA_DIR) và cấu hình engine nên đặt tại ~/.zalo-agent-cli/.env (/.env) để cả zalo-mcp lẫn zalo-agent luôn đọc chung một nguồn cấu hình duy nhất.

---

Sử dụng lệnh zalo-mcp

Sau khi cài đặt (bằng Cách 1 hoặc Cách 2), bạn có thể chạy zalo-mcp trực tiếp từ bất kỳ đâu trong PowerShell, CMD, hoặc Bash mà không cần cd vào thư mục cài đặt hay dùng npm run:

# Khởi chạy MCP server (mặc định: stdio, hoặc thêm --http 3847)
zalo-mcp
zalo-mcp --account 
zalo-mcp --http 3847 --auth  --account  --host 0.0.0.0

# Chuyển tiếp mọi lệnh CLI của zalo-agent-cli (hỗ trợ --account  cho từng lệnh)
zalo-mcp login
zalo-mcp account list
zalo-mcp --account  msg list --json
zalo-mcp --account  listen
zalo-mcp oa init --app-id  --secret 
zalo-mcp --help

---

🔑 Đăng nhập & Xác thực

Mọi thông tin xác thực đều được lưu cục bộ và an toàn trên máy của bạn.

A. Zalo Cá Nhân (API Không chính thức)

1. Chạy lệnh đăng nhập:

   zalo-mcp login
   

   (Hoặc npm run login nếu chạy trong thư mục cài đặt 1-click).
2. Một mã QR sẽ hiển thị trên terminal. Mở app Zalo trên điện thoại > Quét mã QR (đừng dùng camera thường của điện thoại).

[!IMPORTANT] Vị trí lưu trữ Credentials: Mặc định tại ~/.zalo-agent-cli/ (quyền 0600). Có thể tách riêng credentials, database (zalo.db), và media sang các ổ đĩa khác nhau bằng cách khai báo ZALO_CREDENTIALS_DIR, ZALO_DATA_DIR, ZALO_MEDIA_DIR trong ~/.zalo-agent-cli/.env (/.env). Cảnh báo: Đây là API không chính thức, tài khoản cá nhân của bạn có thể bị khóa (ban) nếu dùng để spam liên tục. Không nên dùng nick chính.

B. Zalo Official Account (API v3.0 Chính thức)

1. Khởi tạo kết nối OA:

   zalo-mcp oa init --app-id  --secret 
   

   (Hoặc npm run oa:init -- --app-id --secret trong thư mục cài đặt).
2. Làm theo hướng dẫn trên trình duyệt để ủy quyền ứng dụng.

[!IMPORTANT] Vị trí lưu trữ Credentials: Mặc định tại ~/.zalo-agent/oa-credentials.json (hoặc tùy chỉnh qua ZALO_OA_DIR trong ~/.zalo-agent-cli/.env). OA Access Tokens hết hạn sau 25 giờ. Refresh bất cứ lúc nào bằng lệnh: zalo-mcp oa refresh (hoặc npm run oa:refresh).

---

🤖 Tích hợp AI Agent (MCP)

Khi chạy zalo-mcp (hoặc node mcp-server.js) không có tên lệnh con (chỉ kèm các cờ như --account, --http, --auth, --host, --config, -w/--webhook, --webhook-secret, --no-self-heal, --no-delivered-receipts, --log-level), chương trình sẽ tự động khởi chạy zalo-agent mcp start. Xem chi tiết Ghim tài khoản (--account ).

1. Claude Code (~/.claude/settings.json)

Sử dụng lệnh zalo-mcp toàn cục (1 tài khoản):

{
  "mcpServers": {
    "zalo": {
      "command": "zalo-mcp",
      "args": []
    }
  }
}

Chạy nhiều tài khoản Zalo live cùng lúc (Multi-Account): Mỗi tài khoản có database (zalo.db), thư mục media và daemon.lock tách biệt. Khai báo mỗi tài khoản là một MCP server kèm --account (lấy ID từ zalo-mcp account list) — cả hai tài khoản sẽ hoạt động song song mà không ghi đè accounts.json:

{
  "mcpServers": {
    "zalo-shop-a": {
      "command": "zalo-mcp",
      "args": ["--account", "101"]
    },
    "zalo-shop-b": {
      "command": "zalo-mcp",
      "args": ["--account", "202"]
    }
  }
}

(Trên VPS chạy HTTP mode, khởi chạy mỗi tài khoản trên một port riêng: zalo-mcp --account --http 3847 --auth --host 0.0.0.0. Khi gọi lệnh CLI song song, truyền zalo-mcp --account hoặc đặt biến ZALO_ACCOUNT=.)

Hoặc trỏ trực tiếp tới thư mục cài đặt 1-click:

{
  "mcpServers": {
    "zalo": {
      "command": "node",
      "args": ["/đường/dẫn/tuyệt/đối/zalo-mcp/mcp-server.js"],
      "cwd": "/đường/dẫn/tuyệt/đối/zalo-mcp"
    }
  }
}

2. Cursor

Thêm MCP server mới trong settings của Cursor:

• Name: zalo
• Type: stdio
• Command: zalo-mcp (hoặc zalo-mcp --account , hoặc node /đường/dẫn/tuyệt/đối/zalo-mcp/mcp-server.js)

---

🛠️ Quản lý & Cập nhật

Nếu cài đặt toàn cục qua npm:

• Cập nhật: npm install -g @ardennguyen/zalo-mcp@latest
• Gỡ cài đặt: npm uninstall -g @ardennguyen/zalo-mcp

Nếu dùng thư mục cài đặt 1-click:

• Cập nhật bản mới nhất (Cập nhật engine, node_modules và làm mới liên kết zalo-mcp):
  • Windows: .\zalo-mcp.ps1 update
  • macOS / Linux: ./zalo-mcp.sh update
• Dọn dẹp môi trường (Gỡ liên kết CLI và xóa sạch node_modules để cài lại từ đầu):
  • Windows: .\zalo-mcp.ps1 clean
  • macOS / Linux: ./zalo-mcp.sh clean

---

📖 Tài liệu đầy đủ

Wiki → github.com/ardennguyen/zalo-agent-cli/wiki

Hướng dẫn chi tiết cho tất cả lệnh, thiết lập MCP, cache cục bộ, Official Account API và nhiều hơn nữa — cả tiếng Việt lẫn tiếng Anh.

Giấy phép

zalo-mcp © 2026 Arden Nguyen Duc Huy được cấp phép theo CC BY-NC-SA 4.0. Xem LICENSE và NOTICE.

• Miễn phí cho mục đích phi thương mại: cá nhân, học thuật, nghiên cứu. Không cấp phép cho mục đích thương mại — ví dụ dùng trong sản phẩm thương mại, để cung cấp dịch vụ có thu phí, hoặc trong hoạt động kinh doanh của một công ty. Muốn xin giấy phép thương mại, hãy mở một issue.
• Ghi công: khi chia sẻ dự án này hoặc một phần của nó (nguyên bản hay đã sửa đổi, kể cả bên trong dự án khác), hãy ghi công theo mẫu trong NOTICE, nêu rõ bạn có sửa đổi hay không, và dẫn link giấy phép.
• Chia sẻ tương tự (ShareAlike): bản sửa đổi được chia sẻ phải dùng CC BY-NC-SA 4.0 (hoặc phiên bản mới hơn, hoặc giấy phép tương thích do Creative Commons liệt kê).
• Các phần dẫn xuất từ phần mềm MIT — bản phân phối zalo-mcp gốc của PhucMPham — vẫn thuộc giấy phép MIT; xem NOTICE. Gói này cài @ardennguyen/zalo-agent-cli từ npm; engine đó có LICENSE và NOTICE riêng.
• Các phiên bản phát hành trước thay đổi này (1.0.16 trở về trước) được phát hành theo giấy phép MIT và giữ nguyên các điều khoản đó.

---

---

English

Self-contained Model Context Protocol (MCP) server and CLI wrapper for Zalo. Install globally via npm or use the 1-click sandboxed deployment script so AI agents (Claude Code, Cursor) can automate Zalo Personal & Official Accounts without cluttering your host system. Both installation methods provide the zalo-mcp command directly in your terminal.

[!TIP] What is the difference between zalo-mcp and zalo-agent-cli?

• zalo-agent-cli: The core automation engine. It handles all API logic, authentication, CLI commands, and contains the actual MCP server source code.
• zalo-mcp (This Repo): The lightweight deployment and CLI wrapper. It contains no core engine code—it launches the MCP server and forwards all CLI subcommands to @ardennguyen/zalo-agent-cli. Whether you install it globally (npm i -g @ardennguyen/zalo-mcp) or use the 1-click script (which sets up a sandboxed folder with .env and runs npm link), you can run zalo-mcp from any directory.

📋 Prerequisites

• Node.js: v22 or higher (required for MCP server and CLI).
• Git: Required to pull dependencies.
• @ardennguyen/zalo-agent-cli: zalo-mcp 2.0.5 and later needs engine >=2.5.0 (the package installs a matching version). Engine 2.5.0 and later carries the newest MCP tools and the --webhook / --webhook-secret flags; a new engine tool or flag reaches zalo-mcp once you update (.zalo-mcp.ps1 update / ./zalo-mcp.sh update, or npm install -g @ardennguyen/zalo-mcp@latest for a global install). Engine 2.5.6 and later adds a durable webhook (mcp webhook status), /ready and /metrics, the fleet commands for many accounts, and Markdown messages sent as real Zalo formatting; every flag and subcommand passes through zalo-mcp as usual.

🚀 Quick Start

Choose Option 1 (Global npm install) or Option 2 (One-Line Sandboxed Folder Install). Both methods register the zalo-mcp command on your PATH.

Option 1: Global npm Install (Global CLI)

npm install -g @ardennguyen/zalo-mcp

Option 2: One-Line Sandboxed Installation

Downloads all dependencies into an isolated ./zalo-mcp folder, configures .env for ports (ZALO_MCP_HTTP_PORT), and links the zalo-mcp CLI command globally (npm link):

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.sh | bash -s install

Windows (PowerShell):

Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/ardennguyen/zalo-mcp/main/zalo-mcp.ps1 | Out-File $env:TEMP\zalo-mcp.ps1; & $env:TEMP\zalo-mcp.ps1 install

[!TIP] Recommended .env split: Keep zalo-mcp/.env for PORT settings only (ZALO_MCP_HTTP_PORT). Place storage directory overrides (ZALO_CREDENTIALS_DIR, ZALO_DATA_DIR, ZALO_MEDIA_DIR, ZALO_OA_DIR) and engine settings in ~/.zalo-agent-cli/.env (/.env) so both zalo-mcp and zalo-agent share a single source of truth.

Using the zalo-mcp Command

Once installed (via Option 1 or Option 2), you can run zalo-mcp directly from anywhere in PowerShell, CMD, or Bash without cd-ing into an installation folder or using npm run:

# Start the MCP server (default: stdio, or pass --http 3847)
zalo-mcp
zalo-mcp --account 
zalo-mcp --http 3847 --auth  --account  --host 0.0.0.0

# Pass any zalo-agent-cli command and arguments right through (with optional --account )
zalo-mcp login
zalo-mcp account list
zalo-mcp --account  msg list --json
zalo-mcp --account  listen
zalo-mcp oa init --app-id  --secret 
zalo-mcp --help

🔑 Authentication

A. Personal Zalo Account (Unofficial API)

1. Run the login command:

   zalo-mcp login
   

   (Or npm run login inside a 1-click deployment directory).
2. Scan the printed QR code using the Zalo app on your phone.

[!IMPORTANT] Credentials Storage: Defaults to ~/.zalo-agent-cli/ (0600 permissions). To separate credentials, the SQLite database (zalo.db), and media onto different volumes, set ZALO_CREDENTIALS_DIR, ZALO_DATA_DIR, and ZALO_MEDIA_DIR in ~/.zalo-agent-cli/.env (/.env). Safety Notice: This uses an unofficial API. Your personal account can get banned if heavily abused for spam.

B. Zalo Official Account (Official API v3.0)

1. Initialize OA credentials:

   zalo-mcp oa init --app-id  --secret 
   

   (Or npm run oa:init -- --app-id --secret inside the deployment directory).
2. Follow the browser prompt. Refresh tokens anytime with: zalo-mcp oa refresh (or npm run oa:refresh).

[!IMPORTANT] Credentials Storage: Defaults to ~/.zalo-agent/oa-credentials.json (or customized via ZALO_OA_DIR in ~/.zalo-agent-cli/.env).

🤖 AI Agent Integration (MCP)

When invoked with no subcommand (or only MCP server flags such as --account, --http, --auth, --host, --config, -w/--webhook, --webhook-secret, --no-self-heal, --no-delivered-receipts, --log-level), zalo-mcp starts the MCP server (zalo-agent mcp start). See Account Pinning (--account ) for details.

Claude Code (~/.claude/settings.json):

Using the global zalo-mcp command (single account):

{
  "mcpServers": {
    "zalo": {
      "command": "zalo-mcp",
      "args": []
    }
  }
}

Running multiple live Zalo accounts simultaneously (Multi-Account): Each account has its own isolated SQLite cache (zalo.db), media folder, and daemon.lock. Declare one mcpServers entry per account with --account (from zalo-mcp account list) — both accounts run live in parallel without mutating accounts.json:

{
  "mcpServers": {
    "zalo-shop-a": {
      "command": "zalo-mcp",
      "args": ["--account", "101"]
    },
    "zalo-shop-b": {
      "command": "zalo-mcp",
      "args": ["--account", "202"]
    }
  }
}

(For HTTP mode on a VPS, run each account on its own port: zalo-mcp --account --http 3847 --auth --host 0.0.0.0. For concurrent CLI calls, pass zalo-mcp --account or set ZALO_ACCOUNT=.)

Or pointing directly to the 1-click deployment directory:

{
  "mcpServers": {
    "zalo": {
      "command": "node",
      "args": ["/absolute/path/to/zalo-mcp/mcp-server.js"],
      "cwd": "/absolute/path/to/zalo-mcp"
    }
  }
}

Cursor: Add new MCP server (stdio) -> zalo-mcp (or zalo-mcp --account , or node /absolute/path/to/zalo-mcp/mcp-server.js).

🛠️ Management Commands

• Global npm install:
  • Update: npm install -g @ardennguyen/zalo-mcp@latest
  • Uninstall: npm uninstall -g @ardennguyen/zalo-mcp
• 1-click deployment folder:
  • Update Deps & CLI Link: .\zalo-mcp.ps1 update or ./zalo-mcp.sh update
  • Clean Env & Unlink CLI: .\zalo-mcp.ps1 clean or ./zalo-mcp.sh clean

📖 Documentation

Full Wiki → github.com/ardennguyen/zalo-agent-cli/wiki

Detailed guides for all commands, MCP setup, local cache, Official Account API, and more — available in both English and Tiếng Việt.

---

License

zalo-mcp © 2026 Arden Nguyen Duc Huy is licensed under CC BY-NC-SA 4.0. See LICENSE and NOTICE.

• Free for non-commercial use (personal, academic, research). Commercial use is not licensed — for example in a commercial product, to provide paid services, or in a company’s business operations. To request a commercial license, open an issue.
• Credit required: if you share this project or any part of it, as-is or modified (including inside another project), credit it as shown in NOTICE, say whether you made changes, and link to the license.
• ShareAlike: shared modifications must be released under CC BY-NC-SA 4.0 (or a later version, or a compatible license listed by Creative Commons).
• Portions derived from MIT-licensed software — the original zalo-mcp distribution by PhucMPham — remain under the MIT License; see NOTICE. This package installs @ardennguyen/zalo-agent-cli from npm; that engine carries its own LICENSE and NOTICE.
• Versions published before this change (1.0.16 and earlier) were released under the MIT License and keep those terms.