Drawio Diagramming

Draw.io MCP Server

Architecture / HLA diagrams (infra, Kubernetes, topology)

For polished architecture / High-Level-Architecture diagrams (cloud infra, GKE/k8s clusters, network topology) — not generic flowcharts — follow the dedicated method: read references/architecture-diagrams.md and generate with scripts/gen_arch_drawio.py (box / icon / note / edge / write_mxfile helpers).

Headline rules (full detail in the reference): derive every node from real source code (Terraform/Helm/manifests) before drawing; generate via the Python helper (consistent coords, edges by ID) rather than hand-XML; 64×54 stencil icons (mxgraph.kubernetes.icon / mxgraph.gcp2.*) colored by role; semantic edge colors with a legend; always set explicit exit/entry anchors + waypoints (never target box centers); comb-bus a hub into a single adjacent column; ladder/rail parallel edges ≥13px apart; short centered container titles with qualifiers pushed into dashed notes; keep notes/legend out of edge channels; leave ~40px breathing room at container bottoms. The rest of this file covers the underlying MCP tools and XML mechanics those diagrams build on.

The official draw.io MCP (Model Context Protocol) server that enables LLMs to open and create diagrams in the draw.io editor.

Repository Structure

• mcp-app-server/ — MCP App server (renders diagrams inline in chat via iframe). Hosted at https://mcp.draw.io/mcp. Can also be self-hosted via Node.js or Cloudflare Workers.
• mcp-tool-server/ — Original MCP tool server (stdio-based, opens browser). Published as @drawio/mcp on npm.
• project-instructions/ — Claude Project instructions (no MCP required, no install).
• skill-cli/ — Claude Code skill (generates native .drawio files, opens in desktop app). No MCP required.

Each subdirectory has its own CLAUDE.md with implementation details.

MCP App Server Tool

create_diagram

• Input: { xml: string } - draw.io XML in mxGraphModel format
• Output: Interactive diagram rendered inline via the draw.io viewer library
• Features: Zoom, pan, layers, fullscreen, "Open in draw.io" button

MCP Tool Server Tools

open_drawio_xml

Opens the draw.io editor with XML content.

Parameters:

• content (required): Draw.io XML content
• lightbox (optional): Open in read-only lightbox mode (default: false)
• dark (optional): Dark mode - "true" or "false" (default: false)

Example XML:

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Hello" style="rounded=1;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

open_drawio_csv

Opens the draw.io editor with CSV data that gets converted to a diagram.

⚠️ Note: CSV relies on draw.io's server-side processing and may occasionally fail or be unavailable. Consider using Mermaid for org charts when possible.

Parameters:

• content (required): CSV content
• lightbox (optional): Open in read-only lightbox mode (default: false)
• dark (optional): Dark mode - "true" or "false" (default: false)

⚠️ Avoid using %column% placeholders in style attributes (like fillColor=%color%) - this can cause "URI malformed" errors.

open_drawio_mermaid

Opens the draw.io editor with a Mermaid.js diagram definition.

Parameters:

• content (required): Mermaid.js syntax
• lightbox (optional): Open in read-only lightbox mode (default: false)
• dark (optional): Dark mode - "true" or "false" (default: false)

Quick Decision Guide

Default to Mermaid — it handles most diagram types reliably.

Best Practices for LLMs

1. Default to Mermaid: It handles flowcharts, sequences, ER diagrams, Gantt charts, and more — all reliably
2. Use XML for precision: When you need exact positioning, custom colors, or complex layouts
3. Avoid CSV for critical diagrams: CSV processing can fail; prefer Mermaid for org charts when possible
4. Validate syntax: Ensure Mermaid/CSV/XML syntax is correct before sending
5. Return the URL to users: Always provide the generated URL so users can open the diagram in their browser

Edge Routing Best Practices

CRITICAL: Every edge mxCell must contain a <mxGeometry relative="1" as="geometry" /> child element, even when there are no waypoints. Self-closing edge cells (e.g. <mxCell ... edge="1" ... />) are invalid and will not render correctly. Always use the expanded form:

<mxCell id="e1" edge="1" parent="1" source="a" target="b" style="...">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

draw.io does not have built-in collision detection for edges. You must plan layout and routing carefully:

• Use edgeStyle=orthogonalEdgeStyle for right-angle connectors (most common)
• Space nodes generously — at least 60px apart, prefer 200px horizontal / 120px vertical gaps
• Use exitX/exitY and entryX/entryY (values 0–1) to control which side of a node an edge connects to. Spread connections across different sides to prevent overlap
• Leave room for arrowheads: The final straight segment of an edge (between the last bend and the target shape, or between the source shape and the first bend) must be long enough to fit the arrowhead. The default arrow size is 6px (configurable via startSize/endSize styles). If the final segment is too short, the arrowhead overlaps the bend and looks broken. Ensure at least 20px of straight segment before the target and after the source when placing waypoints or positioning nodes
• When using orthogonalEdgeStyle, the auto-router places bends automatically — if source and target are close together or nearly aligned on one axis, the router may place a bend very close to a shape, leaving no room for the arrow. Fix this by either increasing node spacing or adding explicit waypoints that keep the final segment long enough
• Add explicit waypoints when edges would overlap:

  <mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="a" target="b">
    <mxGeometry relative="1" as="geometry">
      <Array as="points">
        <mxPoint x="300" y="150"/>
        <mxPoint x="300" y="250"/>
      </Array>
    </mxGeometry>
  </mxCell>
  

• Use rounded=1 on edges for cleaner bends
• Use jettySize=auto for better port spacing on orthogonal edges
• Align nodes to a grid (multiples of 10)

Containers and Groups

For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do not just place shapes on top of larger shapes.

How containment works

Set parent="containerId" on child cells. Children use relative coordinates within the container.

Container types

Key rules

• Always add pointerEvents=0; to container styles that should not capture connections being rewired between children. This is critical for usability
• Only omit pointerEvents=0 when the container itself needs to be connectable — in that case, use swimlane style which handles this correctly (the client area is transparent for mouse events while the header remains connectable)
• Children must set parent="containerId" and use coordinates relative to the container

Example: Architecture container

<!-- Swimlane container with title -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- Child inside container (relative coordinates) -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

<!-- Invisible group container -->
<mxCell id="grp1" value="" style="group;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<mxCell id="c1" value="Component A" style="rounded=1;whiteSpace=wrap;" vertex="1" parent="grp1">
  <mxGeometry x="10" y="10" width="120" height="60" as="geometry"/>
</mxCell>

Dark Mode Colors

draw.io supports automatic dark mode rendering. How colors behave depends on the property:

• strokeColor, fillColor, fontColor default to "default", which renders as black (or the system default dark color) in light theme and white (or the system default light color) in dark theme. When no explicit color is set, colors adapt automatically.
• Explicit colors (e.g. fillColor=#DAE8FC) specify the light-mode color. The dark-mode color is computed automatically by inverting the RGB values (blending toward the inverse at 93%) and rotating the hue by 180°. This is done by mxUtils.getInverseColor in the draw.io source code.
• light-dark() function — To specify both light and dark colors explicitly, use light-dark(lightColor,darkColor) in the style string. The first argument is used in light mode, the second in dark mode. Example:

  fontColor=light-dark(#7EA6E0,#FF0000)
  

  This renders the text in blue (#7EA6E0) in light mode and red (#FF0000) in dark mode.

To enable dark mode color adaptation, the mxGraphModel element must include adaptiveColors="auto":

<mxGraphModel adaptiveColors="auto">
  <root>
    ...
  </root>
</mxGraphModel>

When generating diagrams, you generally do not need to specify dark-mode colors — the automatic inversion handles most cases. Use light-dark() only when the automatic inverse color is unsatisfactory and you need precise control over both appearances.

Style Reference

For the complete draw.io style reference including all shape types, edge styles, color palettes, and more, see: https://www.drawio.com/doc/faq/drawio-style-reference.html

For the XML Schema Definition (XSD) for validating .drawio files: https://www.drawio.com/assets/mxfile.xsd

CRITICAL: XML Well-Formedness

When generating draw.io XML, the output must be well-formed XML:

• NEVER use double hyphens (--) inside XML comments. -- is illegal inside <!-- --> per the XML spec and causes parse errors. Use single hyphens or rephrase (e.g. <!-- Order 1 to OrderItem --> not <!-- Order 1 --- OrderItem -->).
• Escape special characters in attribute values (&, <, >, ").

Coding Conventions

• Allman brace style: Opening braces go on their own line for all control structures, functions, objects, and callbacks.

function example()
{
  if (condition)
  {
    doSomething();
  }
  else
  {
    doOther();
  }
}

• Prefer function() expressions over arrow functions for callbacks.

Troubleshooting