AI điều khiển Excalidraw canvas qua MCP

TL;DR

Công cụ cho phép AI agent (Claude, Cursor, Codex) điều khiển Excalidraw canvas một cách lập trình — vẽ, chỉnh sửa, xem lại từng element. Khác với Excalidraw MCP chính thức chỉ generate diagram một lần, tool này cho phép AI vẽ → xem → chỉnh sửa → xem lại, giống như con người đang ngồi vẽ thật.

Nói đơn giản: Cho phép AI vẽ sơ đồ kiến trúc, flowchart bằng câu lệnh, có thể nhìn thấy canvas và chỉnh sửa từng phần.

Bài này dành cho ai?

1. Người muốn AI vẽ sơ đồ thay mình

Vấn đề: Dùng AI generate diagram nhưng không control được từng phần tử, không xem lại được canvas, phải regenerate toàn bộ nếu sai.

Khi nào cần: Cần vẽ architecture diagram, flowchart, system design bằng câu lệnh; muốn AI chỉnh sửa từng shape mà không vẽ lại từ đầu.

Được gì: AI có thể vẽ → chụp ảnh canvas → xem lại → chỉnh sửa element cụ thể. Có 26 tools cho CRUD, align, group, export.

2. Người muốn build sản phẩm AI có visual output

Vấn đề: AI agent cần tạo hình ảnh, sơ đồ nhưng thiếu công cụ để interact với canvas một cách có kiểm soát.

Khi nào cần: Build AI coding assistant, documentation tool, hoặc bất kỳ app nào cần generate diagram từ user prompt.

Được gì: Full canvas API với WebSocket sync, AI có thể “nhìn thấy” canvas qua describe_scene và get_canvas_screenshot.

3. Dev muốn tự động hóa tạo diagram

Vấn đề: Phải vẽ thủ công từng diagram cho documentation, architecture review.

Khi nào cần: Generate diagram từ code, từ Mermaid, hoặc từ prompt của user trong CI/CD pipeline.

Được gì: Tool create_from_mermaid convert Mermaid sang Excalidraw, export_to_excalidraw_url tạo link share được.

Các điểm chính

1. AI giờ “nhìn thấy” canvas mà nó vẽ Tool describe_scene trả về text mô tả các elements, get_canvas_screenshot trả về ảnh. Trước đây AI chỉ vẽ xong không biết kết quả ra sao — giờ có closed feedback loop. → Làm gì: Dùng describe_scene sau mỗi lần vẽ để xác nhận AI hiểu đúng canvas trước khi tiếp tục.

2. 26 tools cho element-level control Full CRUD: create, read, update, delete từng element. Layout tools: align, distribute, group, ungroup. State: snapshot/restore, clear canvas. File I/O: export/import .excalidraw JSON. → Làm gì: Không cần vẽ lại toàn bộ khi cần sửa 1 element — dùng update_element với element ID.

3. So sánh với Excalidraw MCP chính thức MCP chính thức: prompt → diagram (one-shot), stateless, không xem được canvas. Tool này: programmatic control, persistent canvas, AI inspect được scene, iterative refinement được. → Làm gì: Nếu cần quick diagram generation → dùng MCP chính thức. Nếu cần AI control chính xác → dùng repo này.

4. Multi-agent support Nhiều AI agents có thể vẽ trên cùng một canvas cùng lúc, sync qua WebSocket. → Làm gì: Dùng cho team coding session với nhiều AI assistants, hoặc collaborative diagram creation.

5. Agent Skill cho structured workflow Skill đi kèm (skills/excalidraw-skill/) cung cấp step-by-step playbook, cheatsheet, helper scripts cho export/import, CRUD operations. → Làm gì: Copy skill vào ~/.claude/skills/ hoặc ~/.codex/skills/ để dùng /excalidraw-skill command.

6. Design guide tích hợp read_diagram_guide trả về color palette, sizing rules, layout patterns, anti-patterns — giúp AI vẽ diagram đẹp hơn, không còn “diagram AI style” xấu xí. → Làm gì: Gọi read_diagram_guide trước khi bắt đầu vẽ diagram quan trọng.

7. Docker support đầy đủ Có sẵn image ghcr.io/yctimlin/mcp_excalidraw-canvas:latest cho canvas server và ghcr.io/yctimlin/mcp_excalidraw:latest cho MCP server. Cấu hình được cho Claude Desktop, Claude Code, Cursor, Codex CLI, OpenCode, Antigravity. → Làm gì: Không cần Node.js local — chạy hoàn toàn trong Docker nếu muốn.

Quick Start

Tuần này — chạy thử trong 5 phút:

# Terminal 1: Chạy canvas
docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest
# Mở http://localhost:3000 để xem canvas

# Terminal 2: Test MCP (cần clone và build repo trước)
EXPRESS_SERVER_URL=http://localhost:3000 node dist/index.js

Bước tiếp theo:

1. Cấu hình trong Claude Desktop: thêm vào claude_desktop_config.json theo hướng dẫn trong repo
2. Thử prompt: “Vẽ một architecture diagram với 3 services: Auth, API, Database”
3. Dùng describe_scene để xem AI nhìn thấy gì, rồi yêu cầu chỉnh sửa element cụ thể