Draw.io MCP — UML Diagram Generator

drawio-mcp là một MCP server (Model Context Protocol) cho phép bạn sinh UML diagrams chất lượng cao ngay trong quá trình chat với AI — không cần rời khỏi terminal, không cần công cụ vẽ tay.

🎯 Vấn đề & Giải pháp

Trước đây	Với drawio-mcp
Bạn phải tự vẽ diagram bằng tay trong draw.io, LucidChart, hay PlantUML	Bạn mô tả bằng ngôn ngữ tự nhiên, AI sinh file .drawio ngay lập tức
Mất 10–30 phút để kéo thả align từng box	Mất vài giây — AI tự layout chuẩn UML
Không tích hợp được vào AI tools	Là MCP server — kết nối trực tiếp với Claude, Cursor, Codex qua MCP protocol
File không chuẩn, khó chỉnh sửa lại	File .drawio chuẩn — mở bằng diagrams.net, kéo thả chỉnh sửa tiếp được

Kết quả: Bạn tập trung vào thiết kế, AI lo phần trình bày.

✨ Tính năng nổi bật

• 🎯 Tự động layout — không cần chỉ định tọa độ, AI tự sắp xếp theo chuẩn UML
• 🔄 Backward edges / loops — activity diagram hỗ trợ đường vòng (error → retry) với waypoints thông minh
• 🎨 Đúng ký hiệu UML — bullseye end node, filled sync arrows, activation bars, lifelines
• 🏊 Swimlanes — activity diagram có swimlane với topological ordering
• 🔁 Self-loops — sequence diagram hỗ trợ self-message (U-shape)
• 📁 Output chuẩn .drawio — mở được bằng diagrams.net, chỉnh sửa được bằng giao diện kéo thả

📊 Hỗ trợ 4 loại sơ đồ

Diagram	Ký hiệu đặc biệt
Class Diagram	Classes, attributes, methods, stereotypes (interface/abstract/enum), 6 loại relationships
Use Case Diagram	Stick figure actors, white ellipse use cases, system boundary, include/extend/generalization, actor generalization
Activity Diagram	Start/end (bullseye), action, decision, merge, fork/join, swimlanes, backward edges, labeled flows
Sequence Diagram	Participants (actor/boundary/control/entity), lifelines, activation bars, self-loops, 5 message types

---

🚀 Cài đặt

Yêu cầu

• Node.js ≥ 18.0.0
• npm

Clone & build

git clone <repo-url> drawio-mcp
cd drawio-mcp
npm install
npm run build

Kết quả: thư mục dist/ chứa file dist/index.js — đây là entry point của MCP server.

---

⚙️ Cấu hình trên các nền tảng

Claude Code (CLI)

Thêm vào file ~/.claude/settings.json (global) hoặc .claude/settings.local.json (project):

{
  "mcpServers": {
    "drawio-uml": {
      "command": "node",
      "args": ["D:\\path\\to\\drawio-mcp\\dist\\index.js"]
    }
  }
}

Lưu ý: Dùng path tuyệt đối đến thư mục dự án. Trên Windows dùng \\, trên Mac/Linux dùng /.

Claude Desktop

Mở Settings → Developer → MCP Servers → Add → Điền:

Field	Value
Name	drawio-uml
Command	node
Arguments	["D:\\path\\to\\drawio-mcp\\dist\\index.js"]

Hoặc sửa file cấu hình Claude Desktop tại:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "drawio-uml": {
      "command": "node",
      "args": ["D:\\path\\to\\drawio-mcp\\dist\\index.js"]
    }
  }
}

Cursor

Thêm vào file .cursor/settings.json trong project:

{
  "mcpServers": {
    "drawio-uml": {
      "command": "node",
      "args": ["D:\\path\\to\\drawio-mcp\\dist\\index.js"]
    }
  }
}

Codex / Windsurf / Cline / Continue / Các IDE khác

Thêm MCP server với cấu hình tương tự:

{
  "mcpServers": {
    "drawio-uml": {
      "command": "node",
      "args": ["/absolute/path/to/drawio-mcp/dist/index.js"]
    }
  }
}

Sau khi cấu hình, restart IDE. Tools sẽ xuất hiện trong danh sách MCP tools.

---

🛠️ Các MCP Tools

Tool	Description
draw_class_diagram	Create UML class diagram
draw_usecase_diagram	Create use case diagram
draw_activity_diagram	Create activity diagram
draw_sequence_diagram	Create sequence diagram
read_diagram_file	Read & parse existing .drawio file — xem cấu trúc cells, positions, labels, connections
update_diagram_file	Modify existing .drawio file — move, resize, relabel, add/remove cells, thêm edges

Read + Update flow:

1. draw_activity_diagram(...)  → sinh file
2. read_diagram_file({ file_path: "activity-diagram-xxx.drawio" })  → xem cell IDs
3. update_diagram_file({
     file_path: "activity-diagram-xxx.drawio",
     operations: [
       { type: "move_by", cellId: "4", dx: 50, dy: 0 },
       { type: "relabel", cellId: "4", value: "New Label" },
     ]
   })  → sửa file, không cần tạo mới

Sau khi gọi tool tạo/sửa, file .drawio được ghi vào thư mục ./output/.

---

💡 Prompt templates chuẩn

Dưới đây là các prompt đã tối ưu để sinh từng loại diagram. Copy-paste nguyên mẫu và thay đổi thông tin của bạn.

1. Class Diagram

Vẽ class diagram cho hệ thống quản lý thư viện:

- class Book: attributes = [id, title, author, isbn], methods = [borrow(), return()]
- class Member: attributes = [id, name, email], methods = [borrowBook(), returnBook()]
- class Librarian extends Member: attributes = [employeeId]
- class BorrowRecord: attributes = [id, borrowDate, dueDate]
- class Library: attributes = [name, address]

Relationships:
- Librarian → Member (inheritance)
- BorrowRecord → Member (association, "borrowed by")
- BorrowRecord → Book (association, "contains")
- Library → Book (aggregation, "has")

Kết quả: File .drawio với đầy đủ class compartments, stereotypes, relationships đúng UML.

2. Use Case Diagram

Vẽ use case diagram cho hệ thống ATM:

System name: "ATM System"

Actors:
- Customer (mô tả: người dùng ATM)
- Bank Admin (mô tả: quản trị viên ngân hàng)

Use cases:
- "Withdraw Cash" (id: uc1)
- "Deposit Cash" (id: uc2)
- "Transfer Funds" (id: uc3)
- "Check Balance" (id: uc4)
- "Change PIN" (id: uc5)
- "Manage Users" (id: uc6)

Associations:
- Customer → uc1
- Customer → uc2
- Customer → uc3
- Customer → uc4
- Customer → uc5
- Bank Admin → uc6

Relationships:
- uc3 → uc2 (include)  — Transfer cần Deposit để có tiền
- uc5 → uc4 (extend)   — Change PIN có thể cần Check Balance

System boundary: "ATM System" bao gồm tất cả use cases

Kết quả: Stick figure actors bên trái, white ellipse use cases bên phải trong system boundary. Đúng ký hiệu UML chuẩn.

3. Activity Diagram

Vẽ activity diagram cho quy trình đặt hàng online:

Start node: s1
Action nodes:
- login (label: "Log in")
- browse (label: "Browse products")
- cart (label: "Add to cart")
- checkout (label: "Proceed to checkout")
- payment (label: "Process payment")
- confirm (label: "Send confirmation")
- cancel (label: "Cancel order")
- redirect (label: "Redirect to payment gateway")
- verify (label: "Verify payment")

End nodes: e1, e2

Decision nodes:
- d1 (label: "Continue shopping?")
- d2 (label: "Payment successful?")

Flows:
- s1 → login
- login → browse
- browse → cart
- cart → d1
- d1 → checkout (label: "Yes")
- d1 → browse (label: "No")             # backward edge (loop)
- checkout → redirect
- redirect → payment
- payment → d2
- d2 → verify (label: "Yes")
- d2 → payment (label: "No")            # backward edge (loop)
- verify → confirm
- confirm → e1
- checkout → cancel (label: "Cancel")
- cancel → e2

Swimlanes: (tùy chọn — bỏ nếu không cần)
- "Customer" gồm: [s1, login, browse, cart, d1, checkout, cancel]
- "System" gồm: [redirect, payment, d2, verify]
- "Email Service" gồm: [confirm]

Kết quả: Layout theo topological levels, backward edges có waypoints, decision branches có nhãn Yes/No.

Mẹo: Bỏ phần swimlanes nếu muốn layout đơn giản, chỉ giữ lại nodes + flows.

4. Sequence Diagram

Vẽ sequence diagram cho quy trình rút tiền ATM:

Title: "ATM Transaction"

Participants:
- "User" (type: actor)
- "Cây ATM" (type: boundary)
- "Server Ngân Hàng" (type: entity)

Messages:
# ── Authentication ──
- User → Cây ATM: Nhập thẻ (asynchronous, order: 1)
- Cây ATM → User: Yêu cầu mã PIN (asynchronous, order: 2)
- User → Cây ATM: Nhập mã PIN (asynchronous, order: 3)
- Cây ATM → Server Ngân Hàng: Kiểm tra mã PIN (synchronous, order: 4)
- Server Ngân Hàng → Cây ATM: Xác nhận mã PIN (return, order: 5)

# ── Menu ──
- Cây ATM → User: Hiển thị danh sách lựa chọn (asynchronous, order: 6)
- User → Cây ATM: Nhập lựa chọn (asynchronous, order: 7)

# ── Alt: Kiểm tra số dư / Rút tiền / Huỷ ──
# (gán fragment cho mọi message trong block)
- Cây ATM → Server Ngân Hàng: Lấy số dư (synchronous, order: 8)         # fragment: alt, condition: "Kiểm tra số dư / Rút tiền / Huỷ", fromOrder: 8, toOrder: 20
- Server Ngân Hàng → Cây ATM: Trả về số dư (return, order: 9)
- Cây ATM → User: Hiển thị số dư (asynchronous, order: 10)
- Cây ATM → User: Yêu cầu nhập số tiền (asynchronous, order: 11)
- User → Cây ATM: Nhập số tiền (asynchronous, order: 12)
- Cây ATM → Server Ngân Hàng: Kiểm tra số dư (synchronous, order: 13)
- Server Ngân Hàng → Cây ATM: Trả về số dư (return, order: 14)

# ── Nested Alt: Số dư > Số tiền / Số dư < Số tiền ──
- Cây ATM → Server Ngân Hàng: Cập nhật số dư (synchronous, order: 15)   # fragment: alt, condition: "Đủ tiền / Không đủ", fromOrder: 15, toOrder: 19
- Server Ngân Hàng → Cây ATM: Số dư đã được cập nhật (return, order: 16)
- Cây ATM → User: Thông báo "Hãy nhận tiền" (asynchronous, order: 17)
- User → Cây ATM: Nhận tiền (asynchronous, order: 18)
- Cây ATM → User: Thông báo "Số dư không đủ" (asynchronous, order: 19)

# ── Huỷ ──
- Cây ATM → User: Thông báo "Huỷ giao dịch" (asynchronous, order: 20)

# ── Final ──
- Cây ATM → User: In hóa đơn (asynchronous, order: 21)
- Cây ATM → User: Trả thẻ (asynchronous, order: 22)
- User → Cây ATM: Nhận lại thẻ (asynchronous, order: 23)
- Cây ATM → User: Hiển thị cảm ơn (asynchronous, order: 24)

Kết quả: Participants header ngang trên cùng, lifelines dọc, activation bars rỗng viền đen, self-loops vẽ U-shape bên phải.

Mẹo:

• type: "actor" → không có activation bar (đúng UML)
• type: "boundary" / "control" / "entity" → có màu khác nhau
• type: "synchronous" → mũi tên đặc, đường thẳng (sender chờ)
• type: "asynchronous" → mũi tên mở (hói), đường thẳng
• type: "return" → dashed line, gray, open arrow
• Fragment gán vào message đầu tiên của block với fromOrder=order đầu, toOrder=order cuối
• Fragment lồng nhau — tạo fragment thứ 2 với fromOrder/toOrder bên trong fragment ngoài

---

📂 Output

File sinh ra ở ./output/ với tên dạng <prefix>-<timestamp>.drawio.

Mở bằng:

1. app.diagrams.net → File → Open → chọn file
2. Hoặc VS Code extension "Draw.io Integration"

---

🧪 Development

npm run dev        # Chạy MCP server với tsx (hot reload)
npm run test       # Chạy unit tests
npm run build      # Build TypeScript → dist/
npm run inspect    # Test với MCP Inspector

---

🏗️ Kiến trúc dự án

src/
├── index.ts                    # Entry point MCP server (stdio)
├── types/                      # Zod schemas + TypeScript interfaces
│   ├── class-diagram.ts
│   ├── usecase-diagram.ts
│   ├── activity-diagram.ts
│   └── sequence-diagram.ts
├── builders/                   # Sinh mxGraph XML cells
│   ├── base-builder.ts         # Abstract class (ID, addVertex, addEdge, serialize)
│   ├── class-builder.ts
│   ├── usecase-builder.ts
│   ├── activity-builder.ts
│   └── sequence-builder.ts
├── tools/                      # MCP tool definitions
│   ├── class-diagram.ts
│   ├── usecase-diagram.ts
│   ├── activity-diagram.ts
│   └── sequence-diagram.ts
└── utils/
    ├── diagram-writer.ts       # Ghi file .drawio
    ├── compression.ts          # Deflate + base64
    ├── layout.ts               # Grid layout helpers
    └── styles.ts               # draw.io mxGraph styles

---

📝 License

MIT