Skip to content

Latest commit

 

History

History
205 lines (154 loc) · 9.54 KB

CLAUDE.md

File metadata and controls

205 lines (154 loc) · 9.54 KB

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>
  <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

  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

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>

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 (&amp;, &lt;, &gt;, &quot;).

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
"Double hyphen within comment" -- used inside XML comments Remove double hyphens from comments; use words or single hyphens
"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