DOCSEARCHbyAlgolia
Submit Docs

draw.io MCP Server

repository·main·Indexed 26 days ago

https://github.com/jgraph/drawio-mcp

An MCP server and plugin that enables LLMs to create, search, and manipulate diagrams using the draw.io engine. It supports rendering interactive diagrams inline via the @drawio/mcp-app server (compatible with Claude.ai and Cursor) or opening diagrams in a browser via the @drawio/mcp tool server. Features include support for draw.io XML and Mermaid.js syntax, shape library searching, multi-page .drawio file management, and exports to PNG, SVG, and PDF via the Claude Code plugin.

Tokens
36.3K
Snippets
77
Records
165
Agent score
90%

What's inside drawio-mcp

  1. Overview of Draw.io MCP Integration Approaches

    main

    The drawio-mcp repository provides four distinct ways to integrate draw.io with AI assistants. Choose based on your workflow requirements:

    1. MCP App Server: Renders diagrams inline as interactive iframes in chat. Best for Claude.ai, Cursor, or any MCP Apps host. Uses the hosted endpoint https://mcp.draw.io/mcp or can be self-hosted.
    2. MCP Tool Server: Opens diagrams directly in your browser's draw.io editor. Supports XML, CSV, and Mermaid.js. Best for local desktop workflows using Claude Desktop, Cursor, or VS Code.
    3. Assistant Plugins: Native plugins for Claude Code and Codex CLI. Generates .drawio files and can export to PNG, SVG, or PDF using the local draw.io Desktop CLI. Best for local development.
    4. Project Instructions: A zero-install method for Claude.ai Projects that uses Python code execution to generate draw.io URLs. Best for quick setup without MCP.

  2. How the Draw.io Project Instructions workflow works

    main

    The instruction-based workflow follows these steps to ensure link integrity:

    1. Code Generation: Claude generates diagram code in Mermaid, XML, or CSV formats.
    2. Python Execution: Claude executes Python code to compress and encode the diagram.
    3. HTML Output: The Python script outputs a complete HTML page containing the encoded URL embedded as a clickable button.
    4. Artifact Presentation: Claude presents this HTML as an artifact. The user clicks the button to open the diagram in draw.io.

    Note on Reliability: This method uses an HTML output to prevent LLMs from corrupting base64 strings during text generation. By embedding the URL in an HTML artifact via Python, the link is never subject to token-by-token corruption by the LLM.

  3. Understand the Codex drawio plugin structure

    main

    The drawio plugin for Codex is structured to satisfy Codex's requirement that the folder name matches the name field in plugin.json. The plugin root is nested within the codex host directory:

    plugins/codex/
└── drawio/             <-- Codex plugin root (folder name == plugin.json "name")
    ├── .codex-plugin/plugin.json
    ├── skills/drawio/SKILL.md
    ├── assets/drawio-logo.svg
    ├── README.md
    └── DEVELOPING.md

    Key Files:

    • .codex-plugin/plugin.json: The manifest containing metadata and the interface block (display name, logo, brandColor, default prompts).
    • skills/drawio/SKILL.md: The core skill definition. It uses the /drawio:drawio invocation.
    • assets/drawio-logo.svg: The official draw.io logo used for the plugin interface.
    • ../../../.agents/plugins/marketplace.json: The global marketplace manifest that registers this plugin.

  4. Filter elements using Tags

    main

    Tags are visual filters that allow viewers to show or hide elements by category (e.g., "critical", "v2"). Unlike layers, a single element can have multiple tags.

    • Requirement: Tags require wrapping the mxCell in an <object> element.
    • Assignment: Use the tags attribute on the <object> with space-separated strings.
    • Labeling: The label attribute on the <object> replaces the value attribute on the mxCell.
    • Usage: Viewers filter via the draw.io UI (Edit > Tags). Tags do not affect z-order or structural grouping.
    <mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <object id="2" label="Auth Service" tags="critical v2">
      <mxCell style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
        <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
      </mxCell>
    </object>
  </root>
</mxGraphModel>

  5. Run the MCP App Server and MCP Tool Server for development

    main

    To run the different components of the project locally for development, use the following commands in their respective directories:

    # MCP App Server
cd mcp-app-server
npm install
npm start

# MCP Tool Server
cd mcp-tool-server
npm install
npm start

  6. Configure Dark Mode colors

    main

    Draw.io supports automatic dark mode rendering. To enable automatic color adaptation, the mxGraphModel element must include adaptiveColors="auto".

    • Default Colors: Setting strokeColor, fillColor, or fontColor to "default" renders as black in light theme and white in dark theme.
    • Explicit Colors: Explicit colors (e.g., fillColor=#DAE8FC) specify the light-mode color. The dark-mode color is automatically computed by inverting RGB values and rotating the hue.
    • Manual Control: Use the light-dark(lightColor,darkColor) function in the style string to specify distinct colors for each mode (e.g., fontColor=light-dark(#7EA6E0,#FF0000)).

  7. General rules for Mermaid diagrams in draw.io

    main

    When generating Mermaid diagrams for draw.io, follow these syntax rules to ensure correct rendering:

    • Header Keyword: The first non-directive line must be the diagram type keyword (e.g., flowchart TD, sequenceDiagram). Misspelling this results in a blank diagram.
    • Node IDs: Do not use trailing punctuation, spaces, hyphens, or reserved words (end, class, subgraph) in IDs. Use brackets or quotes for display text: A["User's Account"].
    • Statements: Use one statement per line. While ; works as a delimiter in flowcharts, it is not universally supported.
    • Quoting: Use double quotes (") for labels containing special characters (:, -, parentheses, non-ASCII). Avoid single quotes.
    • HTML Labels: Only <br>, <b>, <i>, and <u> are reliably supported.
    • Styling Colors: Use hex codes (#ffffff) for colors; rgb() is not supported.
    • Titles: Use a YAML-style title block at the top for supported types:
      ---
title: My Diagram
---
flowchart TD

  8. Prerequisites for Draw.io Codex Plugin

    main

    To ensure full functionality, including Mermaid conversion, ELK auto-layout, and image exports, ensure the following are installed:

    1. Codex CLI: The host environment for the plugin.
    2. draw.io Desktop: Required for Mermaid-to-diagram conversion, ELK layout passes, and exporting to PNG, SVG, or PDF.

    Note: If you only intend to use plain XML .drawio files or the url output mode, the draw.io Desktop application is not strictly required.

  9. Understand drawio authoring routes

    main

    The plugin uses two primary routes to create native .drawio files. The availability of these routes depends on whether the draw.io desktop CLI is installed on your system.

    1. Mermaid Route (Preferred)

    When the desktop CLI is present, Claude writes a .mmd file and uses the command drawio -x -f xml -o name.drawio name.mmd to convert and layout the diagram. This is the preferred method for standard diagram types.

    2. XML Route

    Claude writes mxGraphModel XML directly to a .drawio file. If the desktop CLI is present, you can optionally apply an ELK layout using: drawio -x -f xml --layout <preset|json> -o name.drawio name.drawio.

    Note: If the draw.io desktop CLI is not available, only the XML route (producing .drawio files or url links) is functional. Mermaid conversion, ELK layout, and image exports (PNG/SVG/PDF) all require the desktop application.

  10. Configure Edge Routing and Layout Passes

    main

    You can upgrade the default basic router (which has no obstacle avoidance) using two independent, opt-in passes on create_diagram:

    1. routing: "libavoid" (XML only): Provides obstacle-avoiding orthogonal edge routing. Vertices stay in their placed positions, but connectors route around shapes. Best for architecture, network topology, and UML.
    2. postLayout: "elk": Performs a full hierarchical re-layout (ELK layered flow). Vertices move to canonical positions. Best for flowcharts and process diagrams. Use direction: "horizontal" for left-to-right flow.

    Selection Guide

    • Neither: Use for sparse layouts where nodes are in clear rows/columns.
    • routing: "libavoid": Use when you have a hand-placed layout but want clean wires that don't cut through boxes.
    • postLayout: "elk": Use when you want a canonical hierarchical layout (vertices will move). Do not set routing when using elk as it is redundant.

    Mermaid Specifics

    For complex Mermaid flowcharts ($\ge$ 20 nodes or complex logic), use postLayout: "elk". Simple flowcharts and non-flowchart types (sequence, class, etc.) do not need it.

  11. Install the Claude Code drawio plugin

    main

    The drawio skill can be installed as a plugin for Claude Code. You can install it directly from the repository's marketplace using the following command:

    /plugin install drawio@drawio

    Alternatively, if you are developing or testing locally, you can load the plugin by pointing Claude to the plugin directory:

    claude --plugin-dir ./plugins/claude-code

  12. Locate the draw.io CLI executable

    main

    Depending on your OS, the drawio executable may be in your PATH or at a specific location. Use these paths to configure your environment.

    • macOS: /Applications/draw.io.app/Contents/MacOS/draw.io
    • Linux (native): drawio (usually via snap/apt/flatpak)
    • Windows (native): C:\Program Files\draw.io\draw.io.exe
    • WSL2: Use the Windows path via /mnt/c/. Example: /mnt/c/Program Files/draw.io/draw.io.exe