The Technique: Text-to-Diagram with Draw.io MCP
You've been there: someone asks for an architecture diagram, and you spend 30 minutes fighting Visio connectors or dragging boxes in PowerPoint. The Draw.io MCP server eliminates that entire workflow. It lets Claude Code generate valid, git-friendly .drawio files from plain text descriptions.
This isn't a toy. The author of the original article generates production diagrams for Dynamics 365 integration architectures, swimlane process flows, and ERDs. The key insight: Draw.io uses mxGraphModel XML, which is text-based and diffs cleanly in git. That means your diagrams become part of your living documentation, versioned alongside your code.
Why It Works: MCP + Structured XML
The Draw.io MCP server runs locally on port 3000. It renders diagrams from mxGraphModel XML. Claude Code connects via the Model Context Protocol (MCP), which Anthropic introduced in November 2024 to standardize AI-to-tool communication. When you describe your system, Claude writes the XML directly—no manual dragging required.
Claude understands diagram semantics. It knows swimlanes have horizontal lanes, ERDs have relationships, and integration maps have system boundaries. It applies consistent color coding when you specify a scheme. The generated XML renders correctly in Draw.io every time.
How To Apply It: Setup and Prompting
Setup
Add the Draw.io MCP server to your .mcp.json config. It runs locally and opens a browser-based editor at localhost:3000 for review.
The Prompt Pattern That Works
Don't say "draw an architecture diagram." Be specific:
Create a Draw.io diagram showing:
- [System A] connects to [System B] via [protocol/method]
- [System C] reads from [System B] on a [schedule]
- Use [color] for [category], [color] for [category]
- Include a legend in the top-right corner
- Layout: left-to-right flow
The more context you give, the better the output. Paste your actual table names, API endpoints, or flow definitions. The author exports Dataverse schemas with XrmToolBox and feeds them directly to Claude for accurate ERDs.
What It Handles Well
Swimlane / process flow Excellent Business processes, approval workflows ERD Good Data models, schema visualization Integration map Good System context, API connections State machine Excellent Lifecycle diagrams Data flow Good ETL pipelines Sequence diagram OK Use Mermaid for these insteadThe 80/20 Rule
Claude generates 80% of the diagram in 30 seconds. You spend 5 minutes on the remaining 20%—positioning overlapping elements and fine-tuning labels. Total: 6 minutes versus 30+ from scratch.
Known Limitations
- Complex layouts: 20+ elements sometimes overlap; you'll drag things manually.
- Pixel-perfect positioning: Approximate. Fine for working docs, not presentation slides.
- Your codebase: Claude doesn't know your table names unless you tell it. Paste schema or API specs.
- Aesthetic polish: Functional, not beautiful. Use Draw.io's manual tools for final polish.
Real Example: D365 Integration Architecture
Prompt: "Create a Draw.io architecture diagram showing: Dynamics 365 CE in the center, connected to Azure AI Search (for document indexing), an external ERP via Azure Service Bus, Power Automate for email notifications, and Dataverse audit log feeding into Power BI. Use blue for Azure services, green for D365, gray for external systems."
30 seconds later: a color-coded diagram with labeled connections and a legend. Compare that to opening Visio and starting from a blank canvas.
Compared to Alternatives
Draw.io + Claude wins on cost (free), AI generation (full diagrams from text), and git friendliness (XML diffs). It loses on real-time collaboration—you collaborate through pull requests, not simultaneous editing. Mermaid is also free and git-friendly, but Draw.io gives you a visual editor for manual adjustments and richer diagram types.
Source: dev.to
