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

History

Visual feedback

_† Requires the companion extension._

Predefined styles

Use the shape parameter in add_node or edgeStyle in add_edge:

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

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

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.

Environment Variables

License

MIT