Draw.io (diagrams.net)¶

Draw.io (now diagrams.net) is a free, open-source, and cross-platform graph drawing software developed in HTML5 and JavaScript. In the July 2026 agentic era, it has evolved into a primary interface for AI-driven architecture visualization through native Model Context Protocol (MCP 3.0) support and the MCP 3.0 Task Protocol for automated execution of visual changes.

What it is¶

Draw.io (v31.0.x as of July 2026) is a professional-grade diagramming tool that provides a wide range of features for creating flowcharts, process diagrams, organizational charts, UML, ER, and network diagrams. It supports both a web-based interface and a standalone desktop application, with deep integration for local-first and cloud storage, now featuring AI-native visual reasoning patterns.

What problem it solves¶

It eliminates the need for expensive, proprietary diagramming software like Microsoft Visio while offering similar or superior capabilities. It provides a platform-agnostic way to create, store, and share visual documentation without vendor lock-in. For AI agents like Gemma 3 and Claude 4.8 Opus, it provides a structured XML-based target (mxGraph) for automated diagram generation and manipulation via the MCP 3.0 Task Protocol.

Where it fits in the stack¶

Draw.io sits in the Documentation and Design layer of the home-office stack. It serves as the primary tool for visualizing architecture, workflows, and complex systems. With the introduction of @drawio/mcp and FastMCP 3.0 hosting, it now acts as a "visual output device" for LLMs to communicate complex structural designs and agentic session states to human operators.

Typical use cases¶

Network Architecture: Designing and documenting home lab or enterprise network layouts.
Software Design: Creating UML diagrams, ER diagrams for databases, and software flowcharts.
Agentic Diagram Generation: Using Gemma 3 or Claude 4.8 Opus to generate complex system diagrams from natural language or CSV data via MCP.
Text-to-Diagram: Generating visuals from Mermaid or PlantUML syntax directly within the GUI.
Cloud Infrastructure: Visualizing AWS, Azure, or GCP deployments using built-in icon sets and AI-assisted layout optimization.

Strengths¶

Privacy-First: No account required; data can be stored locally or on preferred cloud providers.
MCP 3.0 Support: Native integration with the @drawio/mcp server allows agents to open, edit, and export diagrams using the MCP 3.0 Task Protocol.
Extensive Library: Huge collection of icons for networking, cloud, UI design, and more.
Highly Compatible: Can import/export Visio (.vsdx), Lucidchart, and other formats.
Cross-Platform: Available as a web app, desktop app, and can be self-hosted via Docker.

Limitations¶

Collaboration: Real-time collaboration in the self-hosted version is more complex to set up than the SaaS version.
UI Density: The interface can be intimidating for users who only need simple sketching tools (consider Excalidraw for those cases).
XML Complexity: While the .drawio format is XML-based, it uses a compressed mxGraph format that requires specific decoding for direct text-based manipulation.

When to use it¶

When you need to create formal, technical diagrams (UML, Network, Cloud Architecture).
When you want a professional Visio alternative that works across Windows, macOS, and Linux.
When you need to export diagrams to multiple formats (PDF, PNG, SVG, XML) for documentation.
When orchestrating automated architecture updates via AI agents using MCP 3.0.

When not to use it¶

Draw.io is not the best fit for text-native diagrams that must be reviewed primarily in pull requests, generated from code, or diffed line-by-line; use Mermaid or PlantUML for those cases. For informal sketching workshops where a hand-drawn style helps discussion, Excalidraw may be faster.

Getting started¶

Docker (Self-Hosted)¶

To run a private instance of Draw.io using Docker:

docker run -d --name="drawio" -p 8080:8080 -p 8443:8443 jgraph/drawio

Access your instance at http://localhost:8080.

TrueNAS Deployment¶

To host Draw.io on TrueNAS SCALE: 1. Create a Dataset: Create a dataset for optional persistence (e.g., /mnt/pool/apps/drawio). 2. Custom App: - Image: jgraph/drawio:latest - Ports: Map a host port (e.g., 30081) to 8080. 3. Environment: Optionally configure DRAWIO_VIEWER_URL if hosting a custom viewer.

Desktop Installation¶

For offline use, the desktop app is recommended: - Windows/macOS/Linux: Download from the official releases page.

Agentic Integration (MCP 3.0)¶

To allow Claude or other MCP-capable agents to interact with Draw.io, add the following to your configuration:

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

CLI examples¶

Desktop CLI¶

The Draw.io Desktop app includes a CLI for batch processing and conversion:

cat > sample.drawio <<'XML'
<mxfile><diagram name="Page-1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>
XML

# Export a diagram to PDF via CLI (Desktop app required)
drawio -x -f pdf -o sample.pdf sample.drawio

# Export to PNG with a specific width
drawio -x -f png --width 1200 -o sample.png sample.drawio

Advanced: CLI XML Manipulation¶

For automated architecture updates, you can manipulate the underlying XML using standard CLI tools.

# Example: Automatically update a version label in a diagram
sed -i 's/value="v1\.0\.0"/value="v1.1.0"/g' architecture.drawio

# Example: Inspect a container state
docker inspect --format='{{.State.Status}}' drawio

API examples¶

MCP Tool Usage (Gemma 3)¶

The @drawio/mcp server provides tools that agents can call via the MCP 3.0 Task Protocol:

open_diagram: Opens a .drawio file or XML string in the editor.
import_csv: Converts CSV data (e.g., an org chart) into a diagram.
render_mermaid: Converts Mermaid syntax into an editable Draw.io graph.

JSON Protocol¶

When embedding, you can send actions via postMessage:

const iframe = document.getElementById('drawio-iframe');
iframe.contentWindow.postMessage(JSON.stringify({
  action: 'load',
  xml: '<mxfile><diagram name="Page-1"><mxGraphModel><root><mxCell id="0"/><mxCell id="1" parent="0"/></root></mxGraphModel></diagram></mxfile>'
}), '*');

Excalidraw — For hand-drawn style sketching and wireframing.
Obsidian — Can integrate Draw.io diagrams via the "Diagrams.net" plugin.
Mermaid — Text-based diagramming alternative for version control.
Gitea — Recommended for version-controlling .drawio XML files.
Nextcloud — Self-hosted storage backend for diagram synchronization.
Paperless-ngx — For archiving exported diagram PDFs with searchable metadata.
Authentik — For securing the self-hosted Draw.io interface.
Tailscale — For secure remote access to your self-hosted instance.
Trilium — For embedding diagrams into a hierarchical personal knowledge base.
Model Context Protocol — Standard for agentic tool use and integration.

Sources / references¶

Contribution Metadata¶

Last reviewed: 2026-07-07
Confidence: high