Draw.io MCP Server

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

Need	Use	Reliability
Flowchart, sequence, ER diagram	`open_drawio_mermaid`	High
Custom styling, precise positioning	`open_drawio_xml`	High
Org chart from data	`open_drawio_csv`	Medium

Default to Mermaid — it handles most diagram types reliably.

Best Practices for LLMs

Default to Mermaid: It handles flowcharts, sequences, ER diagrams, Gantt charts, and more — all reliably
Use XML for precision: When you need exact positioning, custom colors, or complex layouts
Avoid CSV for critical diagrams: CSV processing can fail; prefer Mermaid for org charts when possible
Validate syntax: Ensure Mermaid/CSV/XML syntax is correct before sending
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

Type	Style	When to use
Group (invisible)	`group;`	Container has no connections and needs no visual border. Includes `pointerEvents=0` so child connections are not captured by the container
Swimlane (titled)	`swimlane;startSize=30;`	Container needs a visible title bar/header, or the container itself has connections
Custom container	`container=1;pointerEvents=0;` added to any shape style	Any shape acting as a container without its own connections

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 include ANY XML comments () in the output. XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
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

Error	Cause	Solution
XML comments in output	`<!-- -->` comments found in generated XML	Remove all XML comments — they are strictly forbidden
"URI malformed"	Special characters in CSV style attributes	Use hardcoded colors instead of `%column%` placeholders
"Service nicht verfügbar"	draw.io CSV server unavailable	Retry later or use Mermaid instead
Blank diagram	Invalid Mermaid/XML syntax	Check syntax, ensure proper escaping
Diagram doesn't match expected	Mermaid version differences	Simplify syntax, avoid edge cases

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

Draw.io MCP Server

Repository Structure

MCP App Server Tool

create_diagram

MCP Tool Server Tools

open_drawio_xml

open_drawio_csv

open_drawio_mermaid

Quick Decision Guide

Best Practices for LLMs

Edge Routing Best Practices

Containers and Groups

How containment works

Container types

Key rules

Example: Architecture container

Dark Mode Colors

Style Reference

CRITICAL: XML Well-Formedness

Coding Conventions

Troubleshooting

`create_diagram`

`open_drawio_xml`

`open_drawio_csv`

`open_drawio_mermaid`