Stop Drawing Diagrams by Hand! Let drawio-mcp Build Them Instantly

What if every architecture review, every system design session, every infrastructure documentation sprint could happen without you touching a single shape tool? What if your AI assistant could generate production-ready diagrams while you describe them in plain English? Here's the painful truth: developers waste hours every week manually dragging boxes, aligning arrows, and hunting for the right AWS or Kubernetes icon in diagram editors. That friction kills momentum. It turns quick explanations into tedious design chores. But what if the loop between thinking and showing collapsed to seconds?

Enter drawio-mcp — the official Model Context Protocol server from the creators of draw.io themselves. This isn't a hacky wrapper or a community plugin. It's the real deal: a bridge between large language models and the world's most popular free diagram editor. Suddenly, your LLM doesn't just talk about systems — it visualizes them. Architecture diagrams, flowcharts, network topologies, UML sequences: generated, rendered, and editable without you lifting a finger. The secret weapon top engineering teams are quietly adopting? This is it. And in this guide, you'll learn exactly how to wield it.

What is drawio-mcp?

drawio-mcp is the official MCP (Model Context Protocol) server developed by JGraph, the team behind draw.io — the diagramming platform used by millions of developers, enterprises, and educators worldwide. Released as an open-source project at github.com/jgraph/drawio-mcp, it represents a fundamental shift in how AI assistants interact with visual content creation tools.

The Model Context Protocol, pioneered by Anthropic, defines a standardized way for AI applications to discover and invoke external tools. drawio-mcp implements this protocol specifically for diagram generation, effectively turning draw.io into a first-class citizen of the AI ecosystem. Instead of LLMs struggling to describe diagrams in text or generating broken images, they now produce native, editable draw.io content through structured tool calls.

Why is this trending right now? Three forces converged: the explosion of AI coding assistants (Claude, GitHub Copilot, Cursor), the standardization around MCP as the "USB-C for AI tools," and the persistent pain point that visual communication remains the last manual bottleneck in otherwise automated development workflows. Engineering teams at scale have realized that architecture decision records, runbooks, and onboarding docs all require diagrams — and those diagrams traditionally demand human hours. drawio-mcp collapses that requirement.

The repository's significance extends beyond convenience. By providing four distinct integration patterns — from zero-install cloud rendering to local CLI workflows — JGraph has made this technology accessible regardless of your infrastructure constraints or security posture. Whether you're a solo developer on Claude.ai or an enterprise team with strict air-gapped requirements, there's a path for you.

Key Features That Make drawio-mcp Insane

Let's dissect what makes this tool genuinely powerful under the hood:

Inline Diagram Rendering via MCP Apps — The MCP App Server leverages the emerging MCP Apps extension to embed interactive diagrams directly in chat interfaces. No context switching. No browser tabs. The diagram lives where the conversation happens, complete with an "Open in draw.io" button for deeper editing. This transforms AI chat from text-only into a visual collaboration surface.

10,000+ Shape Search with Exact Style Strings — The search_shapes tool indexes every shape across all draw.io libraries: AWS, Azure, GCP, Kubernetes, Cisco, UML, BPMN, electrical, P&ID, and more. But here's the critical detail: it returns exact style strings ready for XML insertion. LLMs no longer guess at styling or produce broken shapes. They query, receive precise parameters, and generate valid diagrams programmatically.

Multi-Format Native Support — Unlike approaches that force a single format, the MCP Tool Server handles XML (draw.io's native format), CSV (for rapid data-driven diagrams), and Mermaid.js (for text-to-diagram workflows). This flexibility matters because different teams have different conventions — and drawio-mcp doesn't force migration.

Export Pipeline with Embedded Editability — The Skill + CLI approach generates .drawio files with optional export to PNG, SVG, or PDF. Crucially, exports use --embed-diagram to preserve the underlying XML. Your static image isn't static — it's a Trojan horse containing the full editable diagram. Share it anywhere, open it later in draw.io.

Single Source of Truth XML Reference — All four approaches consume one canonical XML reference file (shared/xml-reference.md). Update edge routing rules, container semantics, or dark mode properties once, and every integration path inherits the improvements. This architectural decision prevents the drift and inconsistency that plague multi-modal tool ecosystems.

Use Cases Where drawio-mcp Absolutely Dominates

1. Architecture Review Automation

You're in a Slack thread debating a new microservices split. Instead of opening draw.io, dragging 40 boxes, and pasting the screenshot, you prompt Claude: "Generate a diagram showing API Gateway → Auth Service → User Service → PostgreSQL, with Redis cache layer." Thirty seconds later, the interactive diagram renders in chat. Stakeholders click to expand. You iterate verbally. The architecture review becomes conversational, not operational.

2. Infrastructure-as-Code Documentation

Your Terraform defines 200 resources. Keeping diagrams synchronized is a nightmare. With drawio-mcp, you pipe terraform show -json through a script that generates CSV, feed it to the MCP Tool Server, and produce annotated infrastructure diagrams that update with every deployment. Documentation drift dies here.

3. Incident Response Runbooks

During an outage, every second counts. Your runbook LLM agent queries your monitoring APIs, identifies affected components, and generates real-time topology diagrams showing blast radius. The search_shapes tool pulls exact Kubernetes pod and service icons. The diagram embeds in your incident channel. Responders see the problem before they read the description.

4. Developer Onboarding at Scale

New hire week three: they're lost in your 50-service platform. You point them to an internal Claude project with drawio-mcp enabled. They ask: "Show me how payment processing works." The LLM generates a sequence diagram with swimlanes, exception flows, and retry logic — all from your existing OpenAPI specs and the XML reference. Onboarding time collapses from weeks to days.

Step-by-Step Installation & Setup Guide

Option A: Zero-Install MCP App Server (Fastest)

No npm. No local files. Perfect for Claude.ai or any MCP Apps-compatible host:

https://mcp.draw.io/mcp

Add this URL as a remote MCP server in your host's settings. Done. The hosted endpoint provides create_diagram and search_shapes immediately.

Option B: Local MCP Tool Server (Full Control)

For Claude Desktop, VS Code extensions, or custom MCP clients:

# Quick start without permanent install
npx @drawio/mcp

# Or install globally for repeated use
npm install -g @drawio/mcp

The package publishes as @drawio/mcp on npm. It supports XML, CSV, and Mermaid with configurable lightbox and dark mode options.

Option C: Skill + CLI for Claude Code

No MCP server required — copy a skill file for local diagram generation:

# Clone the repository
git clone https://github.com/jgraph/drawio-mcp.git
cd drawio-mcp/skill-cli

# Copy the skill file to your Claude Code skills directory
# Location varies by installation; typically:
# ~/.claude/skills/ or your project's .claude/skills/
cp drawio-skill.md /path/to/your/claude/skills/

Ensure draw.io Desktop is installed for file opening and CLI export functionality.

Option D: Project Instructions (Truly Zero Setup)

For Claude.ai Projects, copy the contents of project-instructions/README.md directly into your Project Instructions. No installations, no servers — just paste and prompt.

Development Setup (Contributors)

# MCP App Server (Cloudflare Workers + local dev)
cd mcp-app-server
npm install
npm start

# MCP Tool Server (Node.js stdio transport)
cd mcp-tool-server
npm install
npm start

Both servers read the shared XML reference at startup, ensuring consistent diagram generation behavior.

REAL Code Examples from the Repository

Let's examine actual implementation patterns from the drawio-mcp codebase. These aren't toy examples — they're the mechanisms powering production diagram generation.

Example 1: Shape Search Index Generation

The search_shapes capability requires a pre-built index of all 10,000+ draw.io shapes. Here's how the maintainers generate it from the draw.io client source:

# Generate the shape search index (requires ../drawio-dev checkout)
cd shape-search
npm install

# Point to your local drawio-dev repository
DRAWIO_DEV_PATH=../../drawio-dev node generate-index.js

# Rebuild the MCP App Server worker to embed the updated index
cd ../mcp-app-server
npm run build:worker

What's happening here? The script loads app.min.js from the draw.io client and executes all sidebar palette initializations in a jsdom environment. This captures every shape definition — including style strings, dimensions, and metadata — without manual curation. When draw.io adds new AWS icons or updates Kubernetes symbols, regenerating the index is fully automatic. The resulting search-index.json is committed so the App Server builds without requiring drawio-dev access.

Example 2: Development Server Startup

The repository provides clean separation between the two server implementations:

# MCP App Server — handles inline rendering via MCP Apps protocol
cd mcp-app-server
npm install
npm start

# MCP Tool Server — opens diagrams in browser/editor
cd mcp-tool-server
npm install
npm start

Architecture insight: The App Server targets Cloudflare Workers and modern MCP Apps hosts, using the extensions protocol for iframe embedding. The Tool Server uses stdio transport for local MCP clients like Claude Desktop. Both share shared/xml-reference.md as their prompt engineering foundation, but their transport layers and rendering strategies differ based on deployment context.

Example 3: XML Reference Integration Pattern

All four approaches consume the canonical XML reference. Here's how each accesses it:

Why this matters: When JGraph updates edge routing semantics or adds dark mode properties, they edit one file. The change propagates to hosted servers on next deploy, to npm packages via prepack bundling, to CLI users on their next reference fetch, and to project instructions when users refresh their copy. This eliminates the version skew that destroys LLM tool reliability.

Example 4: Export with Embedded Editability

The Skill + CLI approach uses draw.io Desktop's command-line interface with a critical flag:

# Generate .drawio file (default behavior)
/drawio Create a flowchart for user registration...

# Export to PNG with embedded XML for later editing
/drawio png Create a flowchart for user registration...

The --embed-diagram flag (invoked automatically when formats are specified) preserves the complete draw.io XML inside the PNG/SVG/PDF output. This isn't compression metadata — it's the full diagram structure steganographically encoded. Open that PNG in draw.io later, and it unpacks into editable shapes. This solves the "static image graveyard" problem that plagues technical documentation.

Advanced Usage & Best Practices

Compose with search_shapes before create_diagram — Always query shapes first. The style strings returned ensure your generated XML uses exact, valid references rather than LLM hallucinations. This two-step pattern dramatically improves diagram fidelity.

Leverage CSV for data-heavy diagrams — When visualizing database schemas, cloud resource inventories, or network topologies, generate CSV input rather than hand-crafting XML. The MCP Tool Server's CSV parser handles layout automatically, and you can template the data generation from your actual infrastructure APIs.

Version your Project Instructions — For the no-install approach, snapshot the XML reference contents in your project documentation. When JGraph updates the reference, review changes before adopting them. This prevents surprise behavior shifts in production workflows.

Cache the shape index locally — If running the App Server in bandwidth-constrained environments, pre-build search-index.json and mount it as a volume rather than regenerating on every container start.

Combine with Mermaid for rapid prototyping — Use Mermaid.js input during exploration phases, then convert to native XML once the diagram structure stabilizes. The Tool Server's multi-format support makes this transition seamless.

Comparison with Alternatives

The verdict: drawio-mcp wins where AI automation meets production diagramming. Mermaid excels at quick text-to-diagram in markdown. Excalidraw dominates sketch-style collaboration. But only drawio-mcp closes the loop — LLM-generated, human-editable, enterprise-grade, with the full visual vocabulary of professional technical illustration.

FAQ

Is drawio-mcp free to use?

Yes. The entire project is open-source under standard licenses. The hosted MCP App Server at mcp.draw.io is free for reasonable use. Self-hosted deployments incur only your own infrastructure costs.

Do I need draw.io Desktop installed?

Only for the Skill + CLI approach's file-opening and export features. The MCP App Server and MCP Tool Server work without it. The Project Instructions approach requires no installation whatsoever.

Which LLM hosts support MCP Apps for inline rendering?

Currently Claude.ai supports MCP Apps natively. VS Code MCP extensions and other hosts are adopting the protocol. Without MCP Apps support, diagrams fall back to XML text output — still useful, but not visually embedded.

Can I use this with GPT-4, Gemini, or other LLMs?

The MCP protocol is model-agnostic. Any host implementing MCP can connect to drawio-mcp servers. However, tool calling quality varies by model — Claude's tool use is currently the most reliable for complex diagram generation.

How do I add custom shapes or stencils?

For the shape search index, modify the draw.io client source in your drawio-dev checkout, regenerate the index, and rebuild. For one-off diagrams, use the create_diagram tool with manually specified style strings.

Is my diagram data sent to external servers?

With the hosted App Server, diagram XML transits JGraph's infrastructure. For sensitive data, run the MCP Tool Server locally or use the Skill + CLI approach with air-gapped draw.io Desktop.

Can I automate diagram generation in CI/CD pipelines?

Absolutely. The Skill + CLI approach works headlessly. Generate diagrams from infrastructure definitions on every commit, export to PNG with embedded XML, and publish to your documentation site automatically.

Conclusion

The gap between describing systems and showing them has been a persistent tax on engineering productivity. drawio-mcp eliminates that tax. By marrying the world's most capable free diagram editor with the emerging standard for AI tool integration, JGraph has created something genuinely transformative — not a demo, not a prototype, but a production-ready bridge between language models and visual communication.

Whether you need zero-friction inline diagrams in Claude.ai, fully controlled local generation for security-sensitive environments, or automated documentation pipelines in CI/CD, the four integration paths have you covered. The shape search precision, the embedded editability in exports, the single-source XML reference — these aren't features, they're force multipliers for teams that communicate with diagrams.

Stop dragging boxes. Start describing architectures. Let your LLM handle the visualization while you handle the vision. The future of technical documentation is conversational, automated, and visually rich — and it starts at github.com/jgraph/drawio-mcp. Clone it, configure it, and never draw a diagram by hand again.