zalo-personal-mcp

MCP (Model Context Protocol) server for Zalo Personal Account — biến tài khoản Zalo cá nhân thành công cụ AI thông minh.

Zalo App  <-->  zca-js  <-->  Daemon (background)  <-->  MCP Server (stdio)  <-->  AI Client

Kiến trúc

Dự án sử dụng kiến trúc 2 tiến trình:

1. Daemon (background job) — chạy nền liên tục, giữ session Zalo sống, lắng nghe tin nhắn đến và lưu vào SQLite. Expose HTTP API trên localhost.
2. MCP Server (stdio) — được MCP client (Claude Desktop, Cursor, etc.) spawn qua stdio. Gọi daemon HTTP API để thực hiện actions.

Tại sao tách 2 tiến trình?

• Session sống liên tục: Cookie Zalo hết hạn sau 1 giờ. Daemon tự refresh, ngay cả khi MCP client đóng.
• Inbound as background job: Daemon lắng nghe tin nhắn đến và lưu vào SQLite. AI truy vấn dữ liệu pull-based qua MCP tools.
• Anti-echo: Outbound message IDs được track để tránh bot reply-loop.

Cài đặt

Cài đặt từ npm (khuyến nghị)

# Cài toàn cục
npm install -g zalo-personal-mcp

# Hoặc chạy thẳng không cần cài đặt
npx zalo-personal-mcp login

Cài đặt từ source

git clone https://github.com/lenamuit/zalo-personal-mcp.git
cd zalo-personal-mcp
npm install
npm run build

Sử dụng

1. Đăng nhập Zalo (QR code)

zalo-personal-mcp login

Lệnh này sẽ:

1. Lưu QR code thành file PNG tại ~/.zalo-personal-mcp/qr-code.png
2. Tự động mở file bằng trình xem ảnh mặc định của hệ điều hành
3. In đường dẫn file trong terminal (có thể bấm để mở thủ công)
4. Hiển thị QR ASCII trong terminal làm fallback

Quét QR code bằng app Zalo trên điện thoại. File QR sẽ tự động bị xóa sau khi đăng nhập hoàn tất.

2. Khởi động daemon (chạy nền)

zalo-personal-mcp daemon start

3. Kiểm tra trạng thái

zalo-personal-mcp status

4. Cấu hình MCP Client

Claude Desktop (claude_desktop_config.json)

Cài qua npm toàn cục (sau khi npm install -g zalo-personal-mcp):

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

Hoặc chạy qua npx (không cần cài đặt toàn cục):

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

Nếu cài từ source:

{
  "mcpServers": {
    "zalo-personal": {
      "command": "node",
      "args": ["/path/to/zalo-personal-mcp/dist/bin/cli.js", "mcp"]
    }
  }
}

MCP Tools

Messaging (12 tools)

| Tool | Mô tả | |------|-------| | send_message | Gửi tin nhắn text (hỗ trợ markdown → Zalo rich text) | | send_image | Gửi hình ảnh | | send_link | Gửi link preview | | send_video | Gửi video | | send_voice | Gửi voice message | | send_sticker | Gửi sticker | | send_card | Chia sẻ contact card | | add_reaction | Thêm emoji reaction | | delete_message | Xóa tin nhắn | | undo_message | Thu hồi tin nhắn | | forward_message | Chuyển tiếp tin nhắn | | send_typing | Gửi typing indicator |

Inbound Query (8 tools) — đọc từ SQLite

get_recent_messages, get_unread_messages, search_messages, get_message_context, get_conversations, mark_thread_read, get_auth_status, get_account

Friends (9 tools)

get_friends, get_friend_info, find_user, send_friend_request, accept_friend_request, reject_friend_request, unfriend, get_online_friends, set_friend_nickname

Groups (8 tools)

get_groups, get_group_info, get_group_members, create_group, add_to_group, remove_from_group, leave_group, rename_group

Misc (12 tools)

get_user_info, get_last_online, get_user_qr, mute_conversation, unmute_conversation, pin_conversation, unpin_conversation, create_poll, vote_poll, create_reminder, search_stickers, parse_link

MCP Resources

• zalo://account — Thông tin tài khoản
• zalo://conversations — Danh sách hội thoại
• zalo://friends — Danh sách bạn bè
• zalo://groups — Danh sách nhóm
• zalo://messages/{threadId} — Tin nhắn trong thread

MCP Prompts

• reply_to_thread — Load context để trả lời thread
• summarize_conversation — Tóm tắt hội thoại
• draft_friend_request — Soạn lời mời kết bạn

Tech Stack

| Thư viện | Vai trò | |----------|---------| | @modelcontextprotocol/sdk | MCP TypeScript SDK (v1.x stable) | | zca-js | Zalo API (unofficial) | | better-sqlite3 | SQLite database (sync, fast) | | hono | HTTP server cho daemon | | sharp | Xử lý metadata hình ảnh | | zod | Schema validation |

Cấu trúc dự án

zalo-personal-mcp/
├── src/
│   ├── shared/          # Chia sẻ giữa daemon & MCP server
│   │   ├── types.ts, config.ts, credentials.ts
│   │   ├── zalo-client.ts, db.ts
│   │   ├── store/       # SQLite CRUD (messages, friends, groups, conversations)
│   │   ├── markdown-to-zalo.ts, mention-parser.ts
│   │   └── formatting-guide.ts
│   ├── daemon/          # Background job
│   │   ├── server.ts, listener.ts, keep-alive.ts
│   │   ├── qr-login.ts, name-resolver.ts
│   │   ├── routes/      # HTTP API endpoints
│   │   └── index.ts
│   ├── mcp/             # MCP server (stdio)
│   │   ├── server.ts, daemon-client.ts
│   │   ├── tools/       # MCP tool registrations
│   │   ├── resources.ts, prompts.ts
│   │   └── index.ts
│   └── bin/cli.ts       # CLI entry point
├── tests/               # Unit tests (vitest)
└── scripts/setup.sh

Environment Variables

| Variable | Default | Mô tả | |----------|---------|-------| | ZALO_MCP_PORT | 3712 | Daemon HTTP port | | ZALO_MCP_HOST | 127.0.0.1 | Daemon HTTP host | | ZALO_MCP_DATA_DIR | ~/.zalo-personal-mcp | Data directory |

Commands

# Development
npm run dev:daemon    # Start daemon (tsx)
npm run dev:login     # QR login (tsx)
npm run dev:status    # Check status (tsx)
npm run dev:mcp       # Start MCP server (tsx)

# Build & Test
npm run build         # Compile TypeScript
npm run typecheck     # Type check only
npm test              # Run all tests (vitest)

Yêu cầu hệ thống & Native modules

• Node.js >= 20 (xem engines trong package.json).
• Dự án dùng 2 thư viện native: better-sqlite3 (SQLite) và sharp (xử lý ảnh). Khi npm install, chúng sẽ tự tải prebuilt binary cho các nền tảng phổ biến (macOS / Linux / Windows, x64 / arm64).
• Nếu không có prebuilt khớp, npm sẽ compile từ source — cần:
  • Python 3 (cho node-gyp)
  • macOS: chạy xcode-select --install (cài công cụ build clang)
  • Linux (Debian/Ubuntu): sudo apt install build-essential python3
  • Windows: Visual Studio Build Tools (npm install -g windows-build-tools hoặc cài VS Build Tools).

Disclaimer

• zca-js là thư viện API không chính thức (unofficial), được đảo ngược từ Zalo web. Nó không liên kết và không được bảo trợ bởi Zalo / VNG.
• API có thể gãy bất cứ lúc nào khi Zalo thay đổi giao thức. Việc sử dụng có thể vi phạm Điều khoản dịch vụ (ToS) của Zalo — bạn tự chịu trách nhiệm khi dùng.
• Đây là dự án cá nhân phục vụ học tập / nghiên cứu MCP. Không dùng để spam, quảng cáo, hay bất kỳ hành vi lạm dụng nào.
• Tác giả không chịu trách nhiệm về bất kỳ hậu quả nào (khóa tài khoản, mất dữ liệu, v.v.) phát sinh từ việc sử dụng dự án.

License

MIT © lenamuit