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.

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.

<details> <summary><strong>Claude Desktop</strong></summary>

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"]
    }
  }
}

</details>

<details> <summary><strong>VS Code user settings (all projects)</strong></summary>

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

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

</details>

---

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: <kbd>F1</kbd> → "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