diag2md-mcp
Officialdiag2md-mcp is an MCP server that bridges Draw.io C4/UML diagrams with AI coding agents by converting them to Mermaid Markdown.
list_diagrams: Discovers Draw.io architecture diagram files in the workspace using configurable glob patterns and ignore rules.
convert_diagrams_read: Batch-scans and converts diagrams into Mermaid Markdown, returning the content directly as AI context.
convert_diagrams_write: Batch-scans, converts, and writes updated
.mdfiles alongside the diagram sources for documentation synchronization.Supports
c4andumldiagram types, with defaults configurable viaDIAG2MD_TYPEand per-requestdiagramTypeoverrides.Serves as an architectural guardrail for AI agents, helping enforce C4 system and container boundaries before generating code.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@diag2md-mcp convert all Draw.io diagrams in the architecture folder to Mermaid markdown"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
diag2md-mcp
Model Context Protocol (MCP) server providing AI coding agents with Draw.io C4 and UML architectural guardrails and diagram conversion capabilities.
diag2md-mcp bridges Draw.io architecture diagrams (.xml, .drawio) with AI coding agents (such as Antigravity, Cursor, Claude Desktop, and VS Code MCP clients) by converting C4 and UML diagrams into structured Mermaid Markdown in real time.
Powered by diag2md.
Problem Statement
The Problem: AI coding assistants cannot natively interpret visual architecture diagrams (such as Draw.io files). Without a way to parse these diagrams, AI agents frequently generate code that violates a project's established C4 system and container boundaries.
The Impact: Attempting to solve this by pasting massive, static architectural documents into the AI's prompt severely bloats the context window and reduces the model's performance. As a result, projects suffer from "architectural drift," where the AI-generated codebase slowly misaligns with the intended system design and dependency rules.
The Need: There is a need for a dynamic, on-demand integration (via an MCP server) that translates visual Draw.io C4 diagrams into an AI-readable format (Mermaid Markdown). This solution will serve as a strict, real-time architectural guardrail, ensuring every AI prompt and code change remains aligned with the project's single source of truth.
Why the C4 Model?: The C4 model is the ideal architectural language for this bridge because it caters to both human and machine audiences perfectly. Its hierarchical structure (Context, Containers, Components, Code) provides high-level visual clarity that is easy for non-technical stakeholders and business leaders to understand. Simultaneously, its strict categorization provides the exact deterministic boundaries and structural logic that an AI needs to reason about system architecture, making it the perfect standard for AI-assisted engineering guardrails.
Related MCP server: drawio-mcp
Agent Architectural Guardrails (AGENTS.md / .cursorrules)
You can enforce strict architectural compliance across your team by adding an architectural rule directive to your project's AGENTS.md, GEMINI.md, or .cursorrules:
### ARCHITECTURAL RULES
Before writing any new modules, creating new services, or adding dependencies,
you MUST call the `convert_diagrams_read` MCP tool to verify that proposed changes
align with the C4 Draw.io architecture. Do not suggest structural changes that
violate these boundaries.Key Features
Automated Workspace Discovery: Scans project directories for Draw.io diagram files matching configurable glob patterns (
**/architecture/**/*.xml,**/*.drawio).High-Performance In-Memory Conversion: Converts Draw.io XML models to Mermaid C4 & UML Markdown in-memory without subshell process spawning overhead.
AI Context Provider (
convert_diagrams_read): Reads and converts diagrams dynamically to provide rich architectural context directly to AI coding assistants during chat sessions.Batch Diagram Synchronization (
convert_diagrams_write): Keeps architecture documentation up to date by generating.mdfiles alongside diagram sources.
Quick Start
Running via npx
You can run the MCP server directly without pre-installing:
npx -y diag2md-mcpInstalling Globally
npm install -g diag2md-mcpMCP Server Configuration
To connect diag2md-mcp to your favorite AI assistant or MCP client, add the server to your client configuration file (e.g., mcp_config.json, claude_desktop_config.json, Cursor, or Antigravity MCP settings).
Recommended (Globally Installed Package)
{
"mcpServers": {
"diag2md-mcp": {
"command": "diag2md-mcp"
}
}
}Alternative: Local Built Source
{
"mcpServers": {
"diag2md-mcp": {
"command": "node",
"args": ["/path/to/diag2md-mcp/dist/index.js"]
}
}
}Alternative: On-Demand via npx
{
"mcpServers": {
"diag2md-mcp": {
"command": "npx",
"args": ["-y", "diag2md-mcp"]
}
}
}MCP Tools Reference
diag2md-mcp exposes 3 core tools to AI coding agents:
Tool Name | Description | Arguments |
| Discovers all Draw.io architecture diagram files ( |
|
| Batch scans workspace diagram files matching glob patterns, converts them, and writes updated |
|
| Batch scans workspace diagram files and returns converted Mermaid Markdown directly as context for the AI assistant. |
|
Server Configuration
The MCP server settings can be customized via environment variables:
Environment Variable | Description | Default Value |
| Comma-separated glob patterns to discover diagram files. |
|
| Comma-separated glob patterns to ignore during file discovery. |
|
| Default conversion diagram type ( |
|
Configuration Example with env Patterns
You can configure custom search patterns directly in your MCP server JSON configuration using the env block:
{
"mcpServers": {
"diag2md-mcp": {
"command": "diag2md-mcp",
"env": {
"DIAG2MD_PATTERNS": "**/architecture/**/*.xml, **/docs/**/*.drawio",
"DIAG2MD_IGNORE": "**/tmp/**, **/node_modules/**",
"DIAG2MD_TYPE": "c4"
}
}
}
}Dynamic Tool Call Example with patterns
AI assistants or tools can also override search patterns dynamically per request:
{
"name": "convert_diagrams_read",
"arguments": {
"patterns": [
"**/architecture/**/*.xml",
"**/docs/**/*.drawio"
]
}
}Development
# Clone the repository
git clone https://github.com/diag2md/diag2md-mcp.git
cd diag2md-mcp
# Install dependencies
npm install
# Build TypeScript to JavaScript dist/
npm run build
# Run unit tests
npm run test
# Run type checker
npm run typecheckLicense
Available Tools
3 toolsconvert_diagrams_readA
Batch scan and convert all workspace diagram files (.xml, .drawio) into Mermaid Markdown, returning their content directly as AI context.
Inputs: patterns, diagramType.
convert_diagrams_writeA
Batch scan workspace diagrams matching glob patterns and convert them to updated .md files on disk.
Inputs: patterns, diagramType.
list_diagramsA
Discover all Draw.io architecture diagram files (.xml, .drawio) in the workspace using glob patterns.
Inputs: ignore, patterns.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
list_diagrams is clearly discovery-only, while the two convert tools are separated by output behavior: _write persists .md files to disk and _read returns content as AI context. There is no meaningful overlap between any pair.
All tool names follow a consistent verb_noun pattern in lowercase snake_case, using the same 'diagrams' resource. The _read/_write suffixes are a coherent way to distinguish output modes, and list_diagrams fits the pattern as an independent discovery action.
Three tools is a well-scoped set for a focused converter utility: discover source files, convert to files, and convert to context. Each tool addresses a distinct workflow step without unnecessary expansion.
The core workflow of finding Draw.io diagrams and converting them to Mermaid Markdown is fully covered in both output modes (disk and context). No obvious dead ends or missing lifecycle operations are apparent for this narrow domain.
Maintenance
Related MCP Connectors
Draw architecture diagrams, UML, planning boards and clickable wireframes from your AI assistant.
Let Claude, Cursor, or ChatGPT author Mermaid diagrams your team can read and share.
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to programmatically create, modify, and analyze Draw.io diagrams through the Model Context Protocol. Supports generating architectural diagrams, flowcharts, and visualizations with bidirectional communication between AI systems and Draw.io.131,500MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to generate professional UML diagrams (class, use case, activity, sequence) from natural language descriptions, producing editable .drawio files compatible with diagrams.net.7109 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, read, update, and delete Draw.io diagrams, allowing automated generation of architectural diagrams, flowcharts, and visual documentation.MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents to list, read, create, update, delete, and render PlantUML and Mermaid diagrams, and check them against the actual codebase to detect architecture drift.15108 npm1MIT