Skip to main content
Glama

drawio-mcp

MCP server that lets AI assistants create, read, and edit draw.io diagrams. Pair it with the VS Code draw.io extension and watch diagrams update in real time as the AI works.

Install in VS Code Install in VS Code Insiders

What can it do?

  • Create diagrams — flowcharts, architecture diagrams, sequence diagrams from natural language

  • Read & understand — parse existing .drawio files and describe their structure

  • Edit precisely — add/remove/update individual nodes and edges

  • Undo mistakes — full history with undo/redo, independent of the editor's Ctrl+Z

  • Live preview — changes appear instantly in the VS Code draw.io editor, no reload


Install

Click one of the badges above, or add this to .vscode/mcp.json in your project:

{
  "servers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "github:abossard/drawio-mcp"]
    }
  }
}

Tip: Commit this file to your repo — every contributor gets diagram support automatically.

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "github:abossard/drawio-mcp"]
    }
  }
}

Add to your User settings.json (Cmd+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "servers": {
      "drawio": {
        "command": "npx",
        "args": ["-y", "github:abossard/drawio-mcp"]
      }
    }
  }
}

Related MCP server: Draw.io MCP Server

Usage

Just ask your AI assistant:

"Create a flowchart for a user login process in docs/login-flow.drawio"

"Read architecture.drawio and describe the components"

"Add a Redis cache node between the API and Database, then highlight it"

"Undo the last change"

The server also ships with prompt templates — try asking to "use the architecture prompt" or "use the flowchart prompt".


Tools

Diagram manipulation

Tool

Description

create_diagram

Create a new .drawio file

read_diagram

Parse and return all pages, nodes, and edges

add_node

Add a shape with label, position, size, and style

add_edge

Connect two nodes with optional label and style

update_element

Modify label, style, position, or size

remove_element

Delete a node or edge by ID

add_page

Add a new page/tab

get_diagram_styles

List all predefined styles

History

Tool

Description

undo_last_operation

Restore file to previous state

redo_last_operation

Re-apply last undone change

get_change_history

List recent operations

Visual feedback

Tool

Description

highlight_element

Flash elements with a colored highlight

show_ai_cursor

Show AI cursor position †

show_ai_selection

Highlight AI-selected cells †

show_status

Status bar message †

show_spinner

Loading spinner †

† Requires the companion extension.

Predefined styles

Use the shape parameter in add_node or edgeStyle in add_edge:

Category

Styles

Shapes

rectangle roundedRectangle ellipse diamond parallelogram hexagon triangle cylinder cloud document process star callout

Flowchart

start end decision processStep inputOutput

Architecture

server database firewall user container

UML

actor component package interface

Colors

blue green red yellow purple orange gray

Edges

straight orthogonal curved entityRelation dashed dotted bidirectional noArrow


How it works

AI Assistant ──(MCP)──> drawio-mcp server ──(writes XML)──> .drawio file
                                                                  │
                                              VS Code draw.io extension
                                              detects change & live-merges
                                                        │
                                                   draw.io webview
                                                  (instant update ✨)
  • ✅ No page reload — changes merge seamlessly

  • ✅ Undo works — each write becomes one Ctrl+Z step

  • ✅ User selection preserved — the merge doesn't disrupt anything


Companion Extension (Optional)

The companion VS Code extension adds real-time AI presence overlays to the draw.io editor. Without it the core MCP tools (create, read, edit, undo) work fine — the extension adds the visual extras.

What it adds

Feature

Description

🤖 AI cursor

Shows where the AI is "looking" in the diagram

🔲 Cell selection

Highlights which cells the AI is editing

✨ Flash highlight

Temporary colored flash on elements

💬 Status messages

Shows AI status in the editor (e.g. "Adding database…")

⏳ Spinner

Loading indicator during long operations

📐 Auto-layout

Applies layout algorithms (hierarchical, organic, tree, circle, radial)

Prerequisites

  • draw.io VS Code extension — install from the marketplace or run:

    code --install-extension hediet.vscode-drawio
    # or for Insiders:
    code-insiders --install-extension hediet.vscode-drawio

Install the Bridge Extension

# From the drawio-mcp repo root:
cd vscode-drawio-mcp-bridge
npm install
npm run build
npx @vscode/vsce package --allow-missing-repository

This produces a drawio-mcp-bridge-0.1.0.vsix file. Install it:

code --install-extension ./drawio-mcp-bridge-0.1.0.vsix
# or for Insiders:
code-insiders --install-extension ./drawio-mcp-bridge-0.1.0.vsix

Alternatively, in VS Code: F1 → "Extensions: Install from VSIX…" → select drawio-mcp-bridge-0.1.0.vsix.

Verify

  1. Reload VS Code (Cmd+Shift+P → "Developer: Reload Window")

  2. Open any .drawio file

  3. A small activity log panel appears in the top-left of the draw.io editor showing connection status

  4. Use the MCP tool check_connection to confirm the bridge is connected

The extension auto-connects to the MCP server's WebSocket sidecar when you open a .drawio file. No extra configuration needed.

Settings

Setting

Default

Description

drawioMcpBridge.websocketPort

9219

WebSocket port (must match DRAWIO_MCP_SIDECAR_PORT)

drawioMcpBridge.autoConnect

true

Connect automatically when a .drawio file opens

drawioMcpBridge.aiColor

#D13913

Color for AI cursor and selection overlays

drawioMcpBridge.aiLabel

🤖 AI

Label shown next to the AI cursor

Commands

  • Draw.io MCP: Connect to Server — manually connect to the sidecar

  • Draw.io MCP: Disconnect from Server — disconnect

How it works

┌─────────────────────────────────────────────────┐
│  VS Code                                        │
│                                                 │
│  draw.io extension          drawio-mcp-bridge   │
│  ┌──────────────┐          ┌─────────────────┐  │
│  │ draw.io       │◄─plugin─┤ Injects JS into │  │
│  │ webview       │         │ draw.io iframe   │  │
│  └──────────────┘          └────────┬────────┘  │
│                                     │ WebSocket  │
│                          ┌──────────▼────────┐  │
│                          │ drawio-mcp server  │  │
│                          │ sidecar (:9219)    │  │
│                          └───────────────────┘  │
└─────────────────────────────────────────────────┘

The extension injects a plugin into the draw.io iframe that opens its own WebSocket to the MCP sidecar (ws://127.0.0.1:9219/drawio). AI actions (cursor moves, highlights, status) flow through this channel. User interactions (mouse position, cell selection) are sent back to the MCP server so the AI knows what the user is looking at.


Development

git clone https://github.com/abossard/drawio-mcp.git
cd drawio-mcp
npm install
npm test

Point VS Code at your local build — add to .vscode/mcp.json in any project:

{
  "servers": {
    "drawio-dev": {
      "command": "node",
      "args": ["/absolute/path/to/drawio-mcp/build/index.js"]
    }
  }
}

Run npm run dev for watch mode — VS Code auto-restarts the server on each rebuild.

Command

Description

npm run build

Compile TypeScript

npm run dev

Watch mode (rebuild on save)

npm test

Run tests

npm run test:watch

Watch mode for tests

Environment Variables

Variable

Default

Description

DRAWIO_MCP_SIDECAR_PORT

9219

WebSocket port for companion extension

DRAWIO_MCP_NO_SIDECAR

1

Set to 1 to disable the WebSocket sidecar


License

MIT

Available Tools

21 tools
add_edgeA

Add a connection (edge/arrow) between two nodes in a draw.io diagram.

LAYOUT TIPS for readable diagrams:

  • Use "curved" edgeStyle when multiple edges connect the same pair of nodes, combined with different exitPoint/entryPoint to separate them visually.

  • Use "orthogonal" for clean right-angle routing in architecture diagrams.

  • Use exitPoint/entryPoint to control WHERE on a node the edge connects (e.g. "left", "right", "topLeft25", "bottomRight75") — this prevents edges from stacking on top of each other.

  • For bidirectional flows, use two separate edges with offset connection points (e.g. edge A: exitPoint="rightTop25" → entryPoint="leftTop25", edge B: exitPoint="leftBottom75" → entryPoint="rightBottom75").

Inputs: filePath (required), sourceId (required), targetId (required), id, +6 more.

add_nodeA

Add a new node (shape/vertex) to a draw.io diagram. Use the "shape" parameter for predefined styles, or provide a custom "style" string.

Inputs: label (required), filePath (required), x, y, +6 more.

add_pageB

Add a new page (tab) to a draw.io diagram.

Inputs: filePath (required), pageName (required).

apply_layoutA

Trigger a draw.io built-in automatic layout algorithm on the diagram. Requires the diagram to be open in VS Code with the companion extension connected.

Available layouts:

  • "hierarchical": Best for flowcharts, org charts, architecture diagrams. Arranges nodes in layers by rank.

  • "organic": Force-directed layout. Good for graphs with many cross-connections. Nodes spread out naturally.

  • "tree": Compact tree layout. Best for strict tree/hierarchy structures.

  • "radialTree": Tree layout radiating outward from center.

  • "circle": Arranges all nodes in a circle.

After layout, draw.io saves the updated positions back to the .drawio file automatically.

Inputs: layout (required), spacing, filePath, direction, +1 more.

batch_add_elementsA

Add multiple nodes and edges to a draw.io diagram in a single operation. Much more efficient than calling add_node/add_edge individually — performs only one file read and one file write regardless of how many elements are added. Use this for building entire diagrams or adding multiple components at once.

LAYOUT BEST PRACTICES:

  • Space nodes at least 200px apart horizontally and 150px vertically to leave room for edge labels.

  • Use "curved" edgeStyle when multiple edges connect the same nodes or cross over each other.

  • Use exitPoint/entryPoint (e.g. "left", "right", "topLeft25", "bottomRight75") to separate parallel edges.

  • For bidirectional pairs, use offset connection points so the two arrows don't overlap.

  • All edge labels automatically get a white background for readability.

  • Prefer "orthogonal" for structured layouts and "curved" for organic/many-connection layouts.

Inputs: filePath (required), edges, nodes, layout, +1 more.

check_connectionA

Check the WebSocket sidecar connection status. Reports whether the sidecar server is running and how many companion extension / draw.io plugin clients are connected. Useful for diagnosing live-edit features.

Inputs: no named parameters.

check_layoutA

Analyze a draw.io diagram for layout issues. Returns warnings about:

  • Node overlaps (two nodes occupying the same space)

  • Edge label overlaps with nodes (label text crossing through a node)

  • Edge passes through node (an edge's path visually crosses an intermediate node)

  • Insufficient spacing between connected nodes (label won't fit in the gap)

Each warning includes direction-aware suggestions that consider cascading conflicts — e.g. if moving node A right would collide with node B, the suggestion warns about it and recommends moving B first.

For edge-passes-through-node issues, suggestions include moving the blocking node, changing edge style to "curved" or "orthogonal", or using connection points to reroute.

Call this after building/modifying a diagram to detect readability problems. Use the suggestions to fix issues via update_element.

Inputs: filePath (required), pageIndex.

create_diagramA

Create a new empty draw.io diagram file. The file will be immediately visible in the VS Code draw.io extension.

Inputs: filePath (required), pageName.

get_change_historyA

Get the history of recent MCP operations on draw.io diagrams. Shows operation type, description, timestamp, and affected elements.

Inputs: limit.

get_diagram_stylesA

List all available predefined shape and edge styles for use with add_node and add_edge.

Inputs: no named parameters.

highlight_elementA

Temporarily highlight one or more elements in the draw.io diagram with a flash effect. If the companion extension is connected, uses overlay highlighting. Otherwise, temporarily modifies the element style.

Inputs: filePath (required), elementIds (required), color, durationMs.

read_diagramA

Read and parse a draw.io diagram file, returning a structured overview of all pages, nodes (shapes), and edges (connections).

Inputs: filePath (required).

redo_last_operationA

Redo the last undone MCP operation, re-applying the changes to the diagram file.

Inputs: no named parameters.

remove_elementA

Remove a node or edge from a draw.io diagram by its ID. Also removes any edges connected to a removed node.

Inputs: filePath (required), elementId (required).

screenshot_diagramA

Capture a screenshot (PNG image) of the current draw.io diagram as it appears in the editor. Returns the image so a vision-capable model can analyze the visual layout, styling, and readability. Requires the diagram to be open in VS Code with the companion extension connected.

Inputs: filePath (required), scale, border.

show_ai_cursorB

Show an AI cursor indicator at a specific position in the draw.io diagram. Requires the companion VS Code extension to be connected.

Inputs: x (required), y (required), color, label, +1 more.

show_ai_selectionA

Highlight specific cells in the draw.io diagram as being selected/edited by AI. Shows a colored overlay around the cells. Requires the companion VS Code extension.

Inputs: cellIds (required), color, filePath.

show_spinnerA

Show or hide a loading spinner in the draw.io editor. Use show=true when starting a long operation and show=false when done.

Inputs: show (required), message.

show_statusA

Display a status message in the draw.io editor status bar. Useful for showing what the AI is currently doing. Requires the companion extension.

Inputs: message (required).

undo_last_operationA

Undo the last MCP operation on a draw.io diagram, restoring the file to its previous state. Works independently of the draw.io editor undo.

Inputs: no named parameters.

update_elementA

Update properties of an existing node or edge in a draw.io diagram. Only specified properties are changed.

Inputs: filePath (required), elementId (required), x, y, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists among visual feedback tools (highlight_element, show_ai_selection, show_ai_cursor) and between add_node/add_edge vs batch_add_elements. Description text clarifies these, but an agent might initially confuse them.

    Naming Consistency5/5

    Nearly all tools follow a clear verb_noun snake_case pattern (e.g., create_diagram, read_diagram, add_node, update_element, check_layout, undo_last_operation). Verbs are descriptive and consistent across the set.

    Tool Count4/5

    21 tools is on the higher end but justified for a full-featured diagram editor covering file management, element CRUD, layout, UI feedback, and history. The count feels purposeful rather than bloated.

    Completeness4/5

    The tool surface covers core diagram lifecycle (create, read, update, delete, batch) plus layout, history, and visual feedback. Minor gaps like missing delete_page or get_single_element exist, but read_diagram and update_element work around them.

    Related MCP Connectors

    Related MCP Servers