markus41/plugins/drawio-diagramming/skills/mcp-integration

draw.io MCP Server Integration

Overview

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

1. Official @drawio/mcp (by jgraph) - The official MCP server from the draw.io team
2. 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:

1. Go to Claude.ai Settings > MCP Servers
2. Add server URL: https://mcp.draw.io/mcp
3. 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:

1. Paste the draw.io skill instructions into your Claude Project
2. Ask Claude to create a diagram
3. Claude generates XML and encodes it as a draw.io URL
4. 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:

1. Start with a natural language description
2. AI creates shapes and edges via MCP tools
3. View results in the built-in editor
4. Provide refinement instructions
5. 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