drawio

name drawio description Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mockup, wireframe, or UI sketch, or mentions draw.io, drawio, drawoi, .drawio files, or diagram export to PNG/SVG/PDF. Draw.io Diagram Skill Generate draw.io diagrams as native .drawio files. Author each diagram either as Mermaid (concise text that the draw.io desktop CLI converts and lays out for you) or as draw.io XML directly. Optionally auto-layout XML-authored diagrams with ELK , export to PNG/SVG/PDF with the diagram XML embedded (so the exported file stays editable in draw.io), or generate a browser URL that opens the diagram directly in the draw.io editor. Authoring: Mermaid or XML? The desktop CLI can convert Mermaid to a native .drawio file, so prefer Mermaid for the diagram types it handles well — its parser lays the diagram out automatically, which is far more reliable than hand-positioning cells in XML. Author as Best for Needs desktop CLI? Mermaid Flowcharts, sequence, class, state, ER, gantt, mindmap, timeline, user journey, quadrant, C4, git graph, pie, and other standard types Yes — to convert to .drawio XML Custom styling, precise/hand positioning, specific shape libraries (AWS, Azure, network, UML detail…), or when the desktop CLI is not installed No (optional ELK --layout needs the CLI) Prefer Mermaid when the desktop CLI is available and the request is one of the standard types above — write terse Mermaid and let draw.io lay it out. Use XML for precise control, or as the universal fallback: XML needs no CLI at all, so it's the only option when the desktop app isn't installed (output a .drawio file or a url ). For XML-authored diagrams you can ask the CLI to apply an ELK auto-layout ( --layout ) instead of computing coordinates yourself — the same layouts the draw.io editor's Arrange ▸ Layout menu applies, and the same engine the draw.io MCP app server uses. See ELK layout for XML . If you're unsure whether the desktop CLI is present, detect it first (see Locating the CLI ). No CLI → author as XML and deliver a .drawio file or a url . The pipeline Every diagram becomes a native .drawio file first, then is delivered in the requested output format. This keeps the delivery step identical whether you authored Mermaid or XML. Author → .drawio Mermaid : write the Mermaid to a .mmd file, then convert it with the CLI: drawio -x -f xml -o diagram.drawio diagram.mmd Delete the .mmd afterward — the .drawio is the artifact. draw.io's Mermaid parser has already laid the diagram out, so no --layout is needed. XML : write the mxGraphModel XML to diagram.drawio (see XML format ). Optionally apply an ELK layout (see ELK layout for XML ). Deliver (identical for both sources): (no format) → keep diagram.drawio and open it. png / svg / pdf → export from the .drawio with embedded XML, then delete the source .drawio : drawio -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio url → build a browser URL from the .drawio XML, open it, and keep the .drawio as a local copy (see Browser URL output ). Open the result — the exported file, the URL, or the .drawio . If the open command fails, print the absolute path (or URL) so the user can open it manually. Always convert Mermaid to .drawio first, then export — do not export a .mmd straight to an image. Direct Mermaid → PNG export with -e is broken in current draw.io Desktop (the embedded-XML step crashes); the two-step path (convert, then export the .drawio ) is reliable and produces an editable embed. See Troubleshooting . If Mermaid was requested but no desktop CLI is available, fall back to authoring the same diagram directly as XML. ELK layout for XML XML-authored diagrams can be auto-positioned by the CLI's --layout pass — the same ELK layouts as the editor's Arrange ▸ Layout menu and the same engine the draw.io MCP app server uses. Generate the cells with approximate (or even 0,0 ) positions and let ELK place them; you only have to get the graph structure — nodes and edges — right. Add --layout <name> to any CLI call that reads your XML. The simplest form lays out in place after you write the file (reading and overwriting the same path is supported): drawio -x -f xml --layout verticalFlow -o diagram.drawio diagram.drawio Or combine layout with export in a single call (works for XML input): drawio -x -f png -e -b 10 --layout verticalFlow -o diagram.drawio.png diagram.drawio Layout presets Name Layout verticalFlow Layered, top-to-bottom — flowcharts, pipelines horizontalFlow Layered, left-to-right verticalTree Tree, top-down — hierarchies, org charts horizontalTree Tree, left-to-right radialTree Radial tree organic Force-directed — networks, mind-map-like graphs Custom layout JSON For finer control, pass a JSON array (starting with [ ) instead of a preset name — the same format as the editor's custom-layout dialog: drawio -x -f xml --layout '[{"layout":"elkLayered","config":{"elk.direction":"RIGHT"}}]' -o diagram.drawio diagram.drawio Each entry is {"layout": <algorithm>, "config": { … }} : Algorithms : elkLayered , elkTree , elkRadial , elkOrganic , elkStress , elkBox . config : keys starting with elk. are ELK options — e.g. elk.direction ( UP / DOWN / LEFT / RIGHT ), elk.spacing.nodeNode , elk.layered.spacing.nodeNodeBetweenLayers . The keys edgeStyle (e.g. orthogonal ) and corners (e.g. rounded ) control connector rendering. Orthogonal edge routing --layout libavoid routes the edges orthogonally around the shapes (the editor's Arrange ▸ Layout ▸ Orthogonal Routing ) without moving any vertex — the complement of the node layouts above. Use it as an in-place pass on hand-positioned XML whose connectors cross shapes: drawio -x -f xml --layout libavoid -o diagram.drawio diagram.drawio Skip it after a flow/tree preset — those already route their edges. When to use it: author the graph structure as XML without worrying about coordinates, then apply verticalFlow / horizontalFlow for flow-style diagrams or organic for networks. Mermaid-authored diagrams are already laid out — don't add --layout . Mermaid syntax reference When authoring Mermaid, fetch and follow the shared Mermaid reference (all supported diagram types plus flowchart styling — style , classDef , linkStyle ): https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/mermaid-reference.md Match the language of the diagram labels to the user's language. Choosing the output format Check the user's request for a format preference. Examples: /drawio:drawio create a flowchart → Mermaid → flowchart.drawio /drawio:drawio png flowchart for login → Mermaid → login-flow.drawio.png /drawio:drawio svg: ER diagram → Mermaid → er-diagram.drawio.svg /drawio:drawio pdf AWS architecture overview → XML (needs AWS shapes) → architecture-overview.drawio.pdf /drawio:drawio url flowchart for user login → opens browser at app.diagrams.net with the diagram, keeps login-flow.drawio locally If no format is mentioned, just produce the .drawio file and open it in draw.io. The user can always ask to export later. Supported export formats Format Embed XML Notes png Yes ( -e ) Viewable everywhere, editable in draw.io svg Yes ( -e ) Scalable, editable in draw.io pdf Yes ( -e ) Printable, editable in draw.io jpg No Lossy, no embedded XML support PNG, SVG, and PDF all support --embed-diagram — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Browser URL output When the user requests url format, generate a draw.io URL that opens the diagram directly in the browser editor at app.diagrams.net — no draw.io Desktop required to view it. (Mermaid-authored diagrams still need the desktop CLI to convert to .drawio first; if no CLI is available, author the diagram as XML and build the URL from that.) How it works The .drawio file is written to disk as usual (gives the user a persistent local copy they can re-edit) The XML is compressed with Node.js's built-in zlib and base64-encoded The result is embedded in a https://app.diagrams.net/#create=... URL The URL is opened in the default browser This uses only Node.js built-in modules ( zlib , child_process ) — no external dependencies. URL generation Run this node -e one-liner to read the .drawio file and print the URL (replace DIAGRAM.drawio with the actual filename): URL=$(node -e ' const fs = require("fs"); const zlib = require("zlib"); const xml = fs.readFileSync(process.argv[1], "utf8"); const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64"); const payload = encodeURIComponent(JSON.stringify({ type: "xml", compressed: true, data: compressed })); console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#create=" + payload); ' "DIAGRAM.drawio" ) The URL format matches the MCP Tool Server. Node.js's zlib.deflateRawSync and pako.deflateRaw both implement RFC 1951 and produce identical output, so URLs from either source are interchangeable. Opening the URL Environment Command macOS open "$URL" Linux (native) xdg-open "$URL" WSL2 Write a temp .url file, open via cmd.exe (see below) Windows (native) Write a temp .url file, open via start (see below) Why the .url workaround on Windows/WSL2? cmd.exe 's start command treats & as a command separator and strips everything after # in URLs. The diagram payload lives in the #create=... fragment, so passing the URL directly causes it to be silently lost. A .url shortcut file preserves the URL intact. macOS / Linux example: open " $URL " # macOS xdg-open " $URL " # Linux WSL2 example: TMPFILE=$( mktemp --suffix=.url) printf '[InternetShortcut]\r\nURL=%s\r\n' " $URL " > " $TMPFILE " cmd.exe /c start "" " $(wslpath -w " $TMPFILE " ) " Windows (native) example: Do not build the .url file with echo URL=%URL% . The generated URL contains & characters ( ?grid=0&pv=0&... ) that cmd.exe treats as command separators, so the shortcut is written truncated and the diagram payload is lost — the exact failure the .url file is meant to prevent. Let Node write the file directly (it already holds the URL string) and open only the resulting path, which never contains & : TMPFILE=$(node -e ' const fs = require("fs"); const os = require("os"); const path = require("path"); const p = path.join(os.tmpdir(), "drawio.url"); fs.writeFileSync(p, "[InternetShortcut]\r\nURL=" + process.argv[1] + "\r\n"); process.stdout.write(p); ' " $URL " ) cmd.exe /c start "" " $TMPFILE " After opening Print the URL so the user can copy or share it, and confirm the local file path: Opened in browser: <URL> Local file: DIAGRAM.drawio The .drawio file stays on disk so the user can re-edit it later, attach it elsewhere, or export it to an image format on demand. URL length The URL embeds the full compressed diagram in its hash fragment. Very large diagrams may hit browser URL length limits (typically ~32K–2MB depending on the browser). For complex diagrams that exceed the limit, fall back to writing the .drawio file and opening it locally. draw.io CLI The draw.io desktop app includes a command-line interface used for converting Mermaid to .drawio , applying ELK layouts ( --layout ), and exporting to PNG/SVG/PDF. All three require the desktop app to be installed. Locating the CLI First, detect the environment, then locate the CLI accordingly: WSL2 (Windows Subsystem for Linux) WSL2 is detected when /proc/version contains microsoft or WSL : grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2" On WSL2, use the Windows draw.io Desktop executable via /mnt/c/... : DRAWIO_CMD= "/mnt/c/Program Files/draw.io/draw.io.exe" Double-quote the path so the space in Program Files is treated as part of the path. Do not wrap it in backticks — in bash, backticks are command substitution, which would try to execute the binary at locate-time instead of storing its path. If draw.io is installed in a non-default location, check common alternatives: # Default install path "/mnt/c/Program Files/draw.io/draw.io.exe" # Per-user install (if the above does not exist) "/mnt/c/Users/ $WIN_USER /AppData/Local/Programs/draw.io/draw.io.exe" macOS /Applications/draw.io.app/Contents/MacOS/draw.io Linux (native) drawio # typically on PATH via snap/apt/flatpak Windows (native, non-WSL2) "C:\Program Files\draw.io\draw.io.exe" Use which drawio (or where draw.io on Windows) to check if it's on PATH before falling back to the platform-specific path. Convert / layout / export commands Convert Mermaid to .drawio : drawio -x -f xml -o diagram.drawio diagram.mmd