drawio-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@drawio-mcp Create a flowchart for user login process in login.drawio"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
.drawiofiles and describe their structureEdit 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.drawioand 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 a new |
| Parse and return all pages, nodes, and edges |
| Add a shape with label, position, size, and style |
| Connect two nodes with optional label and style |
| Modify label, style, position, or size |
| Delete a node or edge by ID |
| Add a new page/tab |
| List all predefined styles |
History
Tool | Description |
| Restore file to previous state |
| Re-apply last undone change |
| List recent operations |
Visual feedback
Tool | Description |
| Flash elements with a colored highlight |
| Show AI cursor position † |
| Highlight AI-selected cells † |
| Status bar message † |
| Loading spinner † |
† Requires the companion extension.
Predefined styles
Use the shape parameter in add_node or edgeStyle in add_edge:
Category | Styles |
Shapes |
|
Flowchart |
|
Architecture |
|
UML |
|
Colors |
|
Edges |
|
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-repositoryThis 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.vsixAlternatively, in VS Code: F1 → "Extensions: Install from VSIX…" → select drawio-mcp-bridge-0.1.0.vsix.
Verify
Reload VS Code (Cmd+Shift+P → "Developer: Reload Window")
Open any
.drawiofileA small activity log panel appears in the top-left of the draw.io editor showing connection status
Use the MCP tool
check_connectionto 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 |
|
| WebSocket port (must match |
|
| Connect automatically when a |
|
| Color for AI cursor and selection overlays |
|
| 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 testPoint 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 |
| Compile TypeScript |
| Watch mode (rebuild on save) |
| Run tests |
| Watch mode for tests |
Environment Variables
Variable | Default | Description |
|
| WebSocket port for companion extension |
|
| Set to |
License
Available Tools
21 toolsadd_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
Scored across 21 tools
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.
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.
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.
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
Draw architecture diagrams, UML, planning boards and clickable wireframes from your AI assistant.
1Create workflow, sequence, architecture, and mind map diagrams via AI assistants.
Turn calls and notes into process flow diagrams in Claude, ChatGPT, VS Code, Cursor, and Teams.
Create draw.io diagrams in chat from Mermaid or XML, shown live and interactive. 10,000+ shapes.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create and edit draw.io diagrams programmatically, supporting a wide range of diagram types and styles.78 PyPI6MIT
- FlicenseNot gradedqualityFmaintenanceEnables AI assistants to create, read, and manage Draw.io diagrams programmatically through natural language interactions.1-
- AlicenseAqualityDmaintenanceEnables AI agents to generate and edit draw.io diagrams with real-time browser preview.559 npmApache 2.0
- AlicenseAqualityBmaintenanceEnables AI agents to edit diagram/graph structures on a live draw.io canvas and manage local versions via snapshots, restore, and export without embedding a separate LLM or polluting the workspace.7MIT