zalo-mcp

Gói cài đặt độc lập Model Context Protocol (MCP) server cho Zalo. 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.

Tiếng Việt | English

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

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

• Node.js: Phiên bản 20 trở lên (Bắt buộc cho MCP server).

• Python: Phiên bản 3.8 trở lên (Tùy chọn, cần thiết nếu muốn server tự render biểu đồ hoặc PDF report).

• Git: Cần thiết để clone các bản cập nhật phụ thuộc.

Related MCP server: clawd-mcp

🚀 Bắt đầu nhanh (Cài đặt 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. Bạn có thể cài đặt server ở 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 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. Tạo môi trường ảo Python biệt lập (venv/).

5. Tạo file cấu hình .env.

(Lưu ý: Bạn có thể được hỏi nhập Port nếu chạy ở chế độ tương tác, hoặc bạn có thể tự sửa .env sau).

🔑 Đă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:

   npx zalo-agent login

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

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

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

   npx zalo-agent oa init --app-id <YOUR_APP_ID> --secret <YOUR_APP_SECRET>

2. Làm theo hướng dẫn trên trình duyệt để ủy quyền ứng dụng.

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

Đảm bảo cấu hình AI client của bạn trỏ tới file mcp-server.js trong thư mục cài đặt zalo-mcp.

1. Claude Code

Thêm đoạn sau vào mcpServers trong ~/.claude/settings.json:

{
  "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: node /đường/dẫn/tuyệt/đối/zalo-mcp/mcp-server.js

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

Cập nhật bản mới nhất: (Cập nhật engine, node_modules, python deps)

• Windows: .\zalo-mcp.ps1 update

• macOS / Linux: ./zalo-mcp.sh update

Dọn dẹp môi trường: (Xóa sạch mọi deps để 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.

English

Self-contained Model Context Protocol (MCP) server installer for Zalo. A 1-click sandboxed deployment that enables AI agents (Claude Code, Cursor) to automate Zalo Personal & Official Accounts without cluttering your host system.

📋 Prerequisites

• Node.js: v20 or higher.

• Python: v3.8 or higher (Optional, for rendering charts and PDFs).

• Git: Required to pull dependencies.

🚀 Quick Start (One-Line Installation)

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

🔑 Authentication

A. Personal Zalo Account (Unofficial API)

1. Run the login command:

   npx zalo-agent login

2. Scan the printed QR code using the Zalo app on your phone.

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

1. Initialize OA credentials:

   npx zalo-agent oa init --app-id <YOUR_APP_ID> --secret <YOUR_APP_SECRET>

2. Follow the browser prompt. Refresh tokens anytime with: npx zalo-agent oa refresh

🤖 AI Agent Integration (MCP)

Configure your AI clients to run the server in stdio mode:

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

{
  "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 -> node /absolute/path/to/zalo-mcp/mcp-server.js

🛠️ Management Commands

• Update Deps: .\zalo-mcp.ps1 update or ./zalo-mcp.sh update

• Clean Env: .\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

MIT