draw.io MCP Server Integration

Overview

There are two main MCP server options for draw.io integration:

Official @drawio/mcp (by jgraph) - The official MCP server from the draw.io team
Community drawio-mcp-server (by lgazo) - Community-built server with built-in editor

Both enable AI assistants to create, read, update, and manage draw.io diagrams programmatically.

Official @drawio/mcp Server (by jgraph)

The official MCP server operates in multiple modes depending on the deployment context.

Mode 1: MCP App Server (Hosted)

A hosted MCP endpoint that renders diagrams as interactive iframes directly in AI chat interfaces.

Endpoint: https://mcp.draw.io/mcp

Features:

Renders diagrams as interactive iframes in chat (Claude.ai, VS Code chat, MCP Apps hosts)
No installation required
Diagrams are viewable and editable inline
Supports all draw.io diagram types

Configuration for Claude.ai:

Go to Claude.ai Settings > MCP Servers
Add server URL: https://mcp.draw.io/mcp
Diagrams render inline in conversations

Configuration for VS Code (Copilot Chat):

// .vscode/settings.json
{
  "mcp": {
    "servers": {
      "drawio": {
        "type": "http",
        "url": "https://mcp.draw.io/mcp"
      }
    }
  }
}

Mode 2: MCP Tool Server (Local)

A locally-run MCP server that opens diagrams in the draw.io editor.

Installation and Usage:

npx @drawio/mcp

Features:

Opens diagrams in local draw.io editor (desktop or browser)
Supports XML, CSV, and Mermaid.js input formats
Lightbox and dark mode options
Full draw.io editor capabilities

Configuration:

// .mcp.json (project-level)
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Claude Desktop config:

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Mode 3: Skill + CLI

Uses draw.io Desktop's command-line interface for generating native .drawio files and exporting to image formats.

Requirements:

draw.io Desktop application installed
drawio CLI available in PATH

Capabilities:

Generate native .drawio files from XML
Export to PNG, SVG, PDF with --embed-diagram flag for round-trip editing
Batch export multiple pages
Headless rendering (with xvfb-run on Linux)

Export Commands:

# Export to editable SVG
drawio --export --format svg --embed-diagram --output diagram.drawio.svg diagram.drawio

# Export to editable PNG
drawio --export --format png --embed-diagram --output diagram.drawio.png diagram.drawio

# Export to PDF
drawio --export --format pdf --output diagram.pdf diagram.drawio

# Export specific page
drawio --export --format svg --page-index 2 --output page3.svg diagram.drawio

# Export with custom dimensions
drawio --export --format png --width 1920 --border 10 --output diagram.png diagram.drawio

# Crop to content
drawio --export --format svg --crop --output cropped.svg diagram.drawio

Mode 4: Project Instructions

Zero-installation mode that works by pasting draw.io generation instructions directly into a Claude Project's custom instructions. The AI generates clickable draw.io URLs using Python URL encoding.

How it works:

Paste the draw.io skill instructions into your Claude Project
Ask Claude to create a diagram
Claude generates XML and encodes it as a draw.io URL
Click the URL to open in draw.io

URL format:

https://app.diagrams.net/#R<URL-encoded-XML>

Python URL generation:

import urllib.parse

xml = '''<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Hello" style="rounded=1;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>'''

encoded = urllib.parse.quote(xml, safe='')
url = f'https://app.diagrams.net/#R{encoded}'
print(url)

Community drawio-mcp-server (by lgazo)

An open-source MCP server with a built-in web-based draw.io editor and comprehensive CRUD tools.

Installation

# Run directly with npx (recommended)
npx -y drawio-mcp-server --editor

# Or install globally
npm install -g drawio-mcp-server
drawio-mcp-server --editor

Version: 1.8.0+ (MIT License)

Built-in Editor

When started with --editor, the server launches a web-based draw.io editor:

http://localhost:3000/

Features:

Full draw.io editor in the browser
Real-time sync with MCP tool operations
No draw.io Desktop installation needed
Supports all draw.io features (shapes, styles, layers, etc.)

CLI Options

drawio-mcp-server [options]

Options:
  --editor          Launch built-in web editor (default port 3000)
  --port <number>   Custom port for the editor
  --file <path>     Open a specific .drawio file on startup
  --help            Show help

MCP Tools Reference

The community server exposes these MCP tools:

Shape Operations

Tool	Description
`create_shape`	Create a new shape (vertex)
`update_shape`	Modify shape properties (position, size, style, label)
`delete_shape`	Remove a shape
`read_shape`	Get shape details (style, geometry, label)

create_shape parameters:

{
  "label": "API Gateway",
  "x": 100,
  "y": 100,
  "width": 140,
  "height": 60,
  "style": "rounded=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
}

update_shape parameters:

{
  "id": "cell-id",
  "label": "Updated Label",
  "x": 200,
  "y": 150,
  "style": "fillColor=#d5e8d4;strokeColor=#82b366;"
}

Edge Operations

Tool	Description
`create_edge`	Create a connector between shapes
`update_edge`	Modify edge properties (label, style, routing)
`delete_edge`	Remove an edge

create_edge parameters:

{
  "source": "source-cell-id",
  "target": "target-cell-id",
  "label": "REST API",
  "style": "edgeStyle=orthogonalEdgeStyle;strokeWidth=2;"
}

Text Operations

Tool	Description
`create_text`	Create a text label element
`update_text`	Modify text properties

Diagram Operations

Tool	Description
`read_diagram`	Get the full diagram structure
`inspect_diagram`	Analyze diagram contents (shapes, edges, layers)
`clear_diagram`	Remove all elements

Layer Operations

Tool	Description
`create_layer`	Create a new diagram layer
`switch_layer`	Change the active layer
`list_layers`	List all layers

Browser Extension

Available for Chrome and Firefox. Enables the MCP server to interact with draw.io running in a browser tab.

Chrome Extension: Search "drawio-mcp" in Chrome Web Store Firefox Extension: Search "drawio-mcp" in Firefox Add-ons

"Vibe Diagramming" Support

The community server is designed for iterative, conversational diagram creation:

Start with a natural language description
AI creates shapes and edges via MCP tools
View results in the built-in editor
Provide refinement instructions
AI updates specific elements without regenerating everything

This is more efficient than regenerating full XML because only changed elements are modified.

Configuration Examples

Project-Level (.mcp.json)

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

Or with the community server:

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "drawio-mcp-server", "--editor"]
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

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

Claude Code CLI

# Add official server
claude mcp add-json drawio '{"command":"npx","args":["-y","@drawio/mcp"]}'

# Add community server with editor
claude mcp add-json drawio '{"command":"npx","args":["-y","drawio-mcp-server","--editor"]}'

VS Code (Copilot / Continue / Roo)

// .vscode/settings.json
{
  "mcp": {
    "servers": {
      "drawio-app": {
        "type": "http",
        "url": "https://mcp.draw.io/mcp"
      },
      "drawio-local": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@drawio/mcp"]
      }
    }
  }
}

Zed Editor

// ~/.config/zed/settings.json
{
  "context_servers": {
    "drawio": {
      "command": {
        "path": "npx",
        "args": ["-y", "@drawio/mcp"]
      }
    }
  }
}

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Windsurf

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Choosing Between Official and Community Servers

Feature	Official @drawio/mcp	Community drawio-mcp-server
Maintained by	jgraph (draw.io team)	Community (lgazo)
License	Proprietary	MIT
Hosted option	Yes (mcp.draw.io)	No
Built-in editor	No (opens draw.io app)	Yes (localhost:3000)
CRUD MCP tools	Limited	Full (shapes, edges, layers)
Inline rendering	Yes (iframes in chat)	No
File export	Yes (via CLI)	Via editor
Mermaid support	Yes	No
CSV import	Yes	No
Browser extension	No	Yes
Desktop app required	For CLI mode	No
Vibe Diagramming	Via chat	Via MCP tools + editor

Recommendation:

Use official @drawio/mcp for Claude.ai inline rendering, VS Code Copilot, or when you need the hosted endpoint
Use community drawio-mcp-server when you need granular CRUD control, a built-in editor, or are building automation workflows

Integration Patterns

Pattern 1: AI Chat Diagram Creation

User: "Create an architecture diagram for my microservices"
  |
  v
AI generates draw.io XML
  |
  v
MCP server renders/opens diagram
  |
  v
User views and refines

Pattern 2: Code-to-Diagram Pipeline

Source code analysis
  |
  v
Extract classes/services/dependencies
  |
  v
Generate draw.io XML programmatically
  |
  v
Save as .drawio.svg in repo
  |
  v
Auto-rendered in GitHub README

Pattern 3: Status Dashboard Updates

Health check API
  |
  v
Python update script (see conditional-formatting skill)
  |
  v
Update .drawio file with status colors
  |
  v
Export to .drawio.svg
  |
  v
Commit to repo (via CI/CD)
  |
  v
Dashboard page auto-updates

Pattern 4: Documentation-as-Code

Developer writes/modifies .drawio file
  |
  v
Git commit triggers CI
  |
  v
CI exports to .drawio.svg (drawio CLI)
  |
  v
SVGs embedded in docs site
  |
  v
Confluence/wiki syncs from Git

Troubleshooting

Common Issues

Issue	Cause	Fix
`npx: command not found`	Node.js not installed	Install Node.js v20+
`EACCES permission denied`	npm global dir permissions	Use `npx -y` or fix npm permissions
Connection refused on port 3000	Port already in use	Use `--port 3001` or kill existing process
MCP server not detected	Wrong config file location	Verify config path for your client
Diagram not rendering	Invalid XML	Run validation script from ai-generation skill
`Cannot find module`	npm cache issue	`npm cache clean --force && npx -y ...`
Timeout on diagram operations	Large diagram	Increase timeout in MCP client config
Editor blank on startup	Browser cache	Clear browser cache, try incognito

Node.js Version Requirements

Both servers require Node.js v20 or later:

node --version  # Must be v20.0.0 or higher

# Install via nvm if needed
nvm install 20
nvm use 20

MCP Client Compatibility

Client	Official @drawio/mcp	Community drawio-mcp-server
Claude.ai	Yes (hosted)	No
Claude Desktop	Yes	Yes
Claude Code CLI	Yes	Yes
VS Code (Copilot)	Yes (hosted + local)	Yes (local)
Cursor	Yes	Yes
Zed	Yes	Yes
Windsurf	Yes	Yes
Continue	Yes	Yes

Debugging MCP Connections

# Test official server
npx @drawio/mcp --help

# Test community server
npx drawio-mcp-server --help

# Check if MCP port is in use
lsof -i :3000

# Run with verbose logging
DEBUG=* npx drawio-mcp-server --editor

# Verify MCP config is valid JSON
python3 -c "import json; json.load(open('.mcp.json'))"

Verifying MCP Server Registration

In Claude Code:

# List registered MCP servers
claude mcp list

# Test connection
claude mcp test drawio