✉️ Mail MCP — Xem & Gửi Email qua MCP Server

Ứng dụng email đầy đủ: MCP server (chuẩn Model Context Protocol) để xem/gửi email qua IMAP/SMTP + Web UI hiện đại để dùng trên trình duyệt. Web UI gọi MCP server qua in-memory MCP client, và cùng MCP server đó có thể kết nối với Claude Desktop, VS Code Copilot, hay bất kỳ MCP client nào qua stdio.

✨ Tính năng

MCP Server (6 tools)

Web UI (Vietnamese)

• 📥 Inbox 3 cột: thư mục + danh sách email + khung đọc, dark/light mode tự động

• 📖 Đọc email: render HTML an toàn (sanitize XSS), text/plain, tải file đính kèm

• ✍️ Soạn email: editor định dạng (B/I/U/list/trích dẫn/link), đính kèm file, reply/reply-all/forward

• 🔍 Tìm kiếm với debounce, đánh dấu đã đọc tự động

• ⚙️ Cài đặt tài khoản trực quan trên UI + kiểm tra kết nối

Related MCP server: Email MCP Server

🚀 Cài đặt

npm install
npm run build

▶️ Chạy

1. Web UI (kèm MCP server nội bộ)

npm start            # hoặc: npm run dev (hot reload)
# Mở http://localhost:3000 — lần đầu sẽ tự mở hộp thoại cấu hình tài khoản

2. MCP server qua stdio (cho Claude Desktop, VS Code Copilot…)

npm run mcp          # hoặc: node dist/index.js

Ví dụ cấu hình claude_desktop_config.json:

{
  "mcpServers": {
    "email-mcp": {
      "command": "node",
      "args": ["/duong/dan/tuyet-doi/to/email-mcp/dist/index.js"]
    }
  }
}

Hoặc cài toàn cục: npm link rồi dùng mcp-email.

⚙️ Cấu hình tài khoản

Có 2 cách (cách sau ghi đè cách trước):

1. File .env — copy từ .env.example và điền thông tin

2. Web UI → Cài đặt — lưu vào settings store (xem bên dưới)

💡 Gmail: bật 2 bước xác minh rồi tạo App password tại myaccount.google.com/apppasswords — không dùng mật khẩu đăng nhập thường.

Nơi lưu cài đặt (settings store) — tự chọn backend

src/config.ts tự động chọn nơi lưu theo môi trường chạy:

EdgeOne không cho ghi filesystem nên khi chạy trên EdgeOne, cấu hình KV binding my_kv trong dashboard EdgeOne Pages → cài đặt lưu vào KV, tự động dùng khi deploy. Chạy local thì dùng file như cũ — không cần đổi code.

🚀 Deploy lên EdgeOne Pages

npm run deploy        # EdgeOne Pages (đã có sẵn cấu hình deploy)

1. Tạo KV namespace trong bảng điều khiển EdgeOne và bind tên my_kv vào Pages project

2. Deploy: thư mục functions/ là entry EdgeOne (functions/index.tsx gọi src/edgeone.ts), public/ là file tĩnh

3. Cài đặt tài khoản nhập qua Web UI sẽ lưu vào KV; hoặc đặt env vars trên dashboard

🗂️ Cấu trúc dự án

src/
├── config.ts          # Cấu hình env + settings store (tự chọn fs/KV) + mask mật khẩu
├── storage.ts         # Tầng lưu trữ: backend KV (EdgeOne) + backend file (Node)
├── email-service.ts   # Lõi IMAP (imapflow) + SMTP (nodemailer)
├── mcp-server.ts      # MCP server: 7 tools, stdio + in-memory client
├── api-app.ts         # Hono REST API (không phụ thuộc Node — chạy được trên EdgeOne)
├── web-server.ts      # Node web server: SPA + serve static (chỉ dùng local)
├── edgeone.ts         # Entry EdgeOne Functions: KV binding + phục vụ file tĩnh
└── index.ts           # CLI: `mcp-email` (stdio) | `mcp-email web` (port 3000)
public/                # Web UI: index.html + style.css + app.js
functions/             # EdgeOne Pages entry: index.tsx → src/edgeone.ts

🔌 API Web (REST)

🔐 Bảo mật

• Mật khẩu được mask khi trả về API (********)

• HTML email được sanitize (chặn script, iframe, on*, javascript:…) trước khi render

• File .mail-settings.json và .env đã được gitignore — mật khẩu lưu dạng văn bản thuần, chỉ dùng cho máy cá nhân; trên EdgeOne cài đặt nằm trong KV my_kv (được bảo vệ bởi quyền truy cập platform)