Drawio MCP

Draw.io MCP — Diagram Creation & Editing

You are an expert at creating and editing draw.io diagrams via the draw.io MCP server. Diagrams appear in real-time in the user's browser.

Critical: These Are Direct Tool Calls

MCP tools are direct tool calls — NOT CLI commands.

All draw.io MCP tools use the mcp__drawio__ prefix.

Mandatory Workflow

1. start_session        ← always first (opens browser)
2. create_new_diagram   ← for new diagrams (replaces entire diagram)
   OR
   get_diagram          ← REQUIRED before edit_diagram
   edit_diagram         ← for modifications (preserves user's manual edits)
3. export_diagram       ← optional, saves to .drawio / .png / .svg

Rules:

• start_session must be called before any other tool in a new session
• get_diagram MUST be called before edit_diagram — skipping it will silently overwrite the user's manual changes. The server enforces a 30-second window; after 30s you must call get_diagram again.
• create_new_diagram replaces the ENTIRE diagram — only use for new diagrams or complete redraws
• edit_diagram is for targeted adds/updates/deletes to an existing diagram

XML Format

Every diagram is a complete mxGraphModel:

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- all cells go here, parent="1" for top-level -->
    <mxCell id="2" value="Label" style="..." vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="40" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

Layout rules:

• Keep everything within x=0–800, y=0–600 for single-page viewport
• IDs start at "2" (0 and 1 are reserved)
• Space shapes 150–200px apart for clean edge routing

Semantic Design System

Default for workflow, pipeline, and architecture diagrams. Ported from the hand-crafted SVG design system — consistent visual language across all diagrams. Use this unless the user asks for a different theme.

Node Styles

Group / Container Styles

Use as swim-lane or container shapes (set vertex=1 with large geometry to act as a background region):

Edge Styles (Semantic)

Typography (fontStyle bitmask: 1=bold, 2=italic, 4=underline)

Semantic Color Reference

Alternative Palettes

Use when the user explicitly requests a different visual style.

Dark / Tech

nodes:   fillColor=#1e1e2e;strokeColor=#89b4fa;fontColor=#cdd6f4
accents: strokeColor=#a6e3a1 (green), #f38ba8 (red), #cba6f7 (purple)

Pastel / Soft

nodes:   fillColor=#dae8fc;strokeColor=#6c8ebf;fontColor=#333333

Minimal / Mono

nodes:   fillColor=#ffffff;strokeColor=#333333;fontColor=#333333
edges:   endArrow=open;endSize=8;strokeColor=#333333

Bold / AWS

header:  fillColor=#232F3E;strokeColor=#FF9900;fontColor=#ffffff
compute: fillColor=#FF9900;strokeColor=#FF9900;fontColor=#ffffff

Vibrant / UI

primary:   fillColor=#6366f1;strokeColor=#4f46e5;fontColor=#ffffff;shadow=1
secondary: fillColor=#8b5cf6;strokeColor=#7c3aed;fontColor=#ffffff;shadow=1

Common Shape Styles

Layout Rules (Critical — violations cause misaligned diagrams)

1. Center-align all nodes in a flow column

Every node in a vertical flow column must share the same center_x. Mixed center_x values cause orthogonal edges to jog horizontally, routing through text.

Formula: node_x = center_x - node_width / 2

For a container at x=C_x, width=C_w: center_x = C_x + C_w / 2

If subgroups inside the container have a fixed center (e.g. builder nodes at center_x=533), align ALL orchestrator nodes above/below them to that same center_x. Do not place orchestrator nodes at a different x and rely on routing to bridge the gap.

2. Edges between vertically-stacked nodes must be straight vertical

If source and target share the same center_x, use exitX=0.5;exitY=1;entryX=0.5;entryY=0; — the edge routes as a clean vertical line with no horizontal jog.

If they have different center_x values (unavoidable), add an explicit waypoint that steps horizontally above the entry node (at y = target_top - 15) so the jog happens in empty space, not through text:

<mxGeometry relative="1" as="geometry">
  <Array as="points">
    <mxPoint x="[target_center_x]" y="[target_top - 15]"/>
  </Array>
</mxGeometry>

3. Annotation boxes: vertical center must match the connector exit point

For horizontal dashed connectors to annotation boxes, the annotation's vertical center must equal the source element's exit y.

Formula: annotation_y = source_center_y - annotation_height / 2

Example: source diamond center_y=234, annotation height=72 → annotation_y = 234 - 36 = 198.

If the annotation y is wrong the connector angles — it will not be horizontal. Calculate this explicitly before placing annotations.

4. Loopback labels: use edge value, not rotated text cells

Do NOT use standalone mxCell text cells with rotation=-90 as sidebar labels for loopback edges. They render as floating horizontal blocks, not clean sidebar annotations.

Do: Put the label as the edge value — it will appear near the midpoint of the edge in horizontal text, which is readable and unambiguous:

<mxCell id="e-fail" value="FAIL" style="...strokeColor=#ef4444;fontColor=#dc2626;fontSize=11;fontStyle=1;..." edge="1" ...>

For loopbacks with two semantic labels (e.g. "FAIL" on horizontal segment, "Fresh builder" on vertical), use the more important label as value and omit the secondary label.

Edge Routing Rules

• Always specify exitX, exitY, entryX, entryY explicitly — never rely on auto-routing to pick correct connection points
• For bidirectional connections (A↔B), use opposite sides (exitY=0.3 / entryY=0.7)
• Never let multiple edges share the same path — offset using different exit/entry points
• Add curved=1; for smoother bends on complex routes

<!-- Example: clean vertical edge between aligned nodes -->
<mxCell id="e1" value="" style="endArrow=block;endFill=1;strokeColor=#6b7280;strokeWidth=1.5;edgeStyle=orthogonalEdgeStyle;exitX=0.5;exitY=1;entryX=0.5;entryY=0;" edge="1" source="node-a" target="node-b" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

<!-- Example: edge stepping around text via waypoint -->
<mxCell id="e2" value="" style="endArrow=block;endFill=1;strokeColor=#22c55e;strokeWidth=1.5;edgeStyle=orthogonalEdgeStyle;exitX=0.5;exitY=1;entryX=0.5;entryY=0;" edge="1" source="diamond" target="inner-node" parent="1">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="[inner_node_center_x]" y="[inner_node_top - 15]"/>
    </Array>
  </mxGeometry>
</mxCell>

edit_diagram Operations

{ "operations": [
  { "operation": "add",    "cell_id": "new-1",  "new_xml": "<mxCell ...>" },
  { "operation": "update", "cell_id": "2",       "new_xml": "<mxCell ...>" },
  { "operation": "delete", "cell_id": "old-1" }
]}

Always use descriptive cell_id values (e.g. "lambda-fn", "api-gw") — not numeric IDs — for new cells to avoid collisions.

Export

export_diagram({ path: "./diagram.drawio" })   ← XML (default)
export_diagram({ path: "./diagram.png" })       ← PNG (requires open browser tab)
export_diagram({ path: "./diagram.svg" })       ← SVG (requires open browser tab)

PNG/SVG export requires the browser tab to be open and the diagram loaded.

Port & Session Notes

• MCP server uses port 6002 by default; auto-increments to 6003–6020 if occupied
• The next-ai-draw-io desktop app uses port 61337 in production — no conflict
• In dev mode (npm run dev) the desktop app also uses 6002 — conflict likely; set PORT=6003 in MCP env
• The MCP server and the desktop app are separate — the MCP controls a browser-based draw.io embed, not the Electron window

Configuration

Decision Tree

Troubleshooting

"No active session"

Call start_session first — the session resets on MCP server restart.

Browser not updating

Check the browser URL contains ?mcp=<session-id>. If the tab was closed, call start_session again to get a new URL.

Port already in use

Set PORT=6003 in the MCP server env config (.mcp.json or Claude Desktop config).

edit_diagram rejected ("must call get_diagram first")

The 30-second window expired. Call get_diagram then retry edit_diagram immediately.

PNG/SVG export returns "timed out"

The browser tab must be open with the diagram loaded. Navigate to the session URL, wait for the diagram to render, then retry.