Draw.io MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to create, read, and manage Draw.io diagrams programmatically through natural language interactions.

Overview

The Draw.io MCP Server bridges the gap between conversational AI and visual documentation, allowing users to generate professional-quality diagrams without manual drawing effort. Perfect for technical writers, software developers, and anyone who needs to create architecture diagrams, flowcharts, and network diagrams quickly.

Features

Write XML: Create or update diagrams using valid Draw.io XML for complete control over diagram structure
Read Diagrams: Parse and analyze existing Draw.io files with detailed shape and connection information
Add Shapes: Insert new shapes (rectangles, ellipses, diamonds, cylinders, hexagons) into diagrams
Add Connections: Create edges between diagram elements
Export Support: Instructions for exporting to PNG, SVG, and PDF formats

Installation

Prerequisites

Python 3.12 or higher
uv (recommended) or pip

Setup

Option 1: Install from PyPI (coming soon)

pip install drawio-mcp

Option 2: Install from source

git clone <repository-url>
cd drawio-mcp
uv sync --all-extras

Option 3: Build and install locally

git clone <repository-url>
cd drawio-mcp
uv sync --all-extras
uv pip install build
python -m build
pip install dist/drawio_mcp-0.0.1-py3-none-any.whl

Usage

Running the Server

The server communicates via stdio (standard input/output):

# If installed as package
drawio-mcp

# Or run as module
python -m drawio_mcp

# Or run from source
python src/drawio_mcp/__init__.py

Configuration with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "drawio": {
      "command": "drawio-mcp",
      "args": [],
      "env": {}
    }
  }
}

Or if running from source: ``json { "mcpServers": { "drawio": { "command": "/absolute/path/to/drawio-mcp/.venv/bin/python", "args": ["-m", "drawio_mcp"], "env": {} } } } ``

Available Tools

1. `write_diagram_xml` ⭐ PRIMARY TOOL

Write or update a Draw.io diagram file using valid Draw.io XML content. This provides complete control over diagram structure and is the recommended way to create diagrams.

Parameters:

file_path (string): Path where the .drawio file should be saved or updated (creates file and directories if they don't exist)
xml_content (string): Valid Draw.io XML content (must include complete mxfile structure)
validate (boolean, optional): Whether to validate the XML before writing (default: true)

Example: `` Write this XML to a new diagram file at ~/diagrams/custom.drawio: <mxfile host="AI Agent" version="21.6.5" type="device"> <diagram name="My Diagram" id="d1"> <mxGraphModel dx="2037" dy="830" grid="1" gridSize="10"> <root> <mxCell id="0" /> <mxCell id="1" parent="0" /> <mxCell id="shape1" value="Hello" style="whiteSpace=wrap;rounded=1;" vertex="1" parent="1"> <mxGeometry x="100" y="100" width="120" height="60" as="geometry" /> </mxCell> </root> </mxGraphModel> </diagram> </mxfile> ``

Use Cases:

Generate complex diagrams programmatically from code analysis
Convert other diagram formats (Mermaid, PlantUML, etc.) to Draw.io
Batch process diagram creation from data sources
Create custom diagram templates with precise styling
Build flowcharts, architecture diagrams, network topologies, ER diagrams, and more

Key Features:

✅ Creates files and directories automatically if they don't exist
✅ XML validation with detailed error messages
✅ Pretty-printed output for version control
✅ Returns statistics (shapes, connections, file size)

Documentation: See WRITE_XML_TOOL.md for comprehensive documentation, examples, and XML structure reference. See EXAMPLES_XML_TOOL.md for practical use cases and QUICK_REFERENCE_XML.md for quick XML templates.

2. `read_diagram`

Read and parse an existing Draw.io diagram file.

Parameters:

file_path (string): Path to the .drawio or .xml file

Example: `` Read the diagram at ~/diagrams/architecture.drawio and tell me what's in it ``

3. `add_shape`

Add a new shape to an existing diagram.

Parameters:

file_path (string): Path to the diagram file
shape_type (string): Type of shape - rectangle, ellipse, diamond, cylinder, hexagon, rounded_rectangle
text (string): Text content for the shape
x (number): X coordinate position
y (number): Y coordinate position
width (number, optional): Width of the shape (default: 120)
height (number, optional): Height of the shape (default: 60)

Example: `` Add a database cylinder shape labeled "User DB" at position (300, 200) to ~/diagrams/architecture.drawio ``

4. `add_connection`

Add a connection between two shapes.

Parameters:

file_path (string): Path to the diagram file
from_shape (string): ID or text label of the source shape
to_shape (string): ID or text label of the target shape
label (string, optional): Optional label for the connection

Example: `` Connect the "API Server" shape to the "Database" shape in ~/diagrams/architecture.drawio ``

5. `export_diagram`

Get instructions for exporting a diagram to various formats.

Parameters:

file_path (string): Path to the .drawio file
output_path (string): Path for the exported file
format (string): Export format - png, svg, or pdf

Example: `` Export ~/diagrams/architecture.drawio to PNG format at ~/diagrams/architecture.png ``

Creating Diagrams

The primary way to create diagrams is using the write_diagram_xml tool. This gives you complete control over the diagram structure using Draw.io's XML format.

Quick Examples

Simple Flowchart: ``xml <mxfile host="AI Agent" version="21.6.5" type="device"> <diagram name="Process Flow" id="flow1"> <mxGraphModel dx="2037" dy="830" grid="1" gridSize="10"> <root> <mxCell id="0" /> <mxCell id="1" parent="0" /> <mxCell id="start" value="Start" style="whiteSpace=wrap;rounded=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1"> <mxGeometry x="100" y="50" width="120" height="60" as="geometry" /> </mxCell> <mxCell id="end" value="End" style="whiteSpace=wrap;rounded=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1"> <mxGeometry x="100" y="150" width="120" height="60" as="geometry" /> </mxCell> <mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;" edge="1" parent="1" source="start" target="end"> <mxGeometry relative="1" as="geometry" /> </mxCell> </root> </mxGraphModel> </diagram> </mxfile> ``

Architecture Diagram: See WRITE_XML_TOOL.md and EXAMPLES_XML_TOOL.md for comprehensive examples of flowcharts, architecture diagrams, network topologies, and more.

Diagram Types

All diagram types can be created using the write_diagram_xml tool with appropriate XML structure:

Flowcharts

Process flows with start/end nodes, process steps, and decision diamonds.

Architecture Diagrams

System architecture with servers, databases, APIs, and connections showing data flow.

Network Topologies

Network topology diagrams with routers, switches, firewalls, and devices.

ER Diagrams

Entity-relationship diagrams for database schemas showing tables and relationships.

Sequence Diagrams

Interaction diagrams showing message flows between components over time.

Custom Diagrams

Any diagram type supported by Draw.io can be created with the appropriate XML structure.

Resources:

WRITE_XML_TOOL.md - Complete XML reference and shape styles
EXAMPLES_XML_TOOL.md - Real-world examples and use cases
QUICK_REFERENCE_XML.md - Quick templates and snippets

Technical Details

Architecture

MCP Protocol: Uses the Model Context Protocol for AI-tool communication
XML-Based: Direct XML manipulation for maximum flexibility and control
Transport: stdio-based communication for integration with MCP clients

File Format

Generated files use the standard Draw.io XML format (.drawio), which is:

Human-readable XML text format
Editable in Draw.io desktop and web applications
Version control friendly
Compatible with all Draw.io features and libraries
Industry-standard format

Capabilities and Limitations

What You Can Do

✅ Create any diagram type - Full control via XML ✅ Read and analyze diagrams - Parse shapes, connections, and metadata ✅ Precise positioning - Control exact coordinates and sizes ✅ Custom styling - Full access to colors, shapes, and styles ✅ Batch operations - Generate multiple diagrams programmatically ✅ Template-based creation - Reusable diagram patterns

Current Limitations

⚠️ Export functionality - Requires external Draw.io CLI or desktop app for PNG/SVG/PDF export ⚠️ Shape/Connection addition - The add_shape and add_connection tools are limited due to drawpyo constraints; use write_diagram_xml for full control

Current Limitations

Development

Project Structure

drawio-mcp/
├── src/
│   └── drawio_mcp/
│       ├── __init__.py      # MCP server implementation
│       └── __main__.py      # Module entry point
├── dist/                    # Build artifacts
├── examples/                # Example diagrams
├── pyproject.toml          # Project configuration and dependencies
├── README.md               # This file
├── SETUP.md                # Setup guide
└── BUILD_SUMMARY.md        # Build documentation

Dependencies

mcp>=1.0.0: Model Context Protocol SDK
drawpyo>=0.2.0: Draw.io diagram creation library
pytest>=7.0.0: Testing framework (dev)
pytest-asyncio>=0.21.0: Async testing support (dev)

Building

To build the package for distribution:

uv sync --all-extras
python -m build

This creates:

dist/drawio_mcp-0.0.1-py3-none-any.whl (wheel package)
dist/drawio_mcp-0.0.1.tar.gz (source distribution)

Roadmap

Current (v0.0.1)

✅ XML-based diagram creation with full control
✅ Diagram reading and parsing
✅ Shape and connection tools (limited functionality)
✅ Comprehensive documentation and examples

Next Release (v0.1.0)

[ ] Enhanced XML templates library
[ ] Merge functionality for selective updates
[ ] Style preset system
[ ] Auto-layout algorithms
[ ] XML-to-JSON conversion helpers

Future

[ ] Direct export integration (PNG/SVG/PDF)
[ ] Code-to-diagram generators (Python, JavaScript, Java)
[ ] Interactive diagram editor integration
[ ] Multi-page diagram support
[ ] Diagram diffing for version control

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

[Add your license here]

Acknowledgments

Built with MCP Python SDK
Diagram generation powered by drawpyo
Based on Draw.io

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Draw.io MCP Server