Azure Draw.io MCP Server

Generate editable Azure architecture diagrams in Draw.io format using an MCP server.

What’s an MCP Server? Think of it as a plugin for AI assistants like GitHub Copilot or Claude. Once configured, you can simply ask “draw me an Azure architecture diagram” and it generates one for you.

Attribution: This project is inspired by dminkovski/azure-diagram-mcp which generates PNG diagrams using the Python diagrams package. This version outputs editable .drawio files instead.

Table of Contents

• Why Draw.io Instead of PNG?
• What It Does
• Requirements
• Quick Start
  • Option A: Docker
  • Option B: Install from GitHub
  • Option C: Local Python
• Usage Examples
• MCP Tools
• Opening Generated Diagrams
• Example Prompts
• Project Structure
• Troubleshooting
• License

Why Draw.io Instead of PNG?

What It Does

• Generates Azure architecture diagrams as .drawio files
• Uses official Azure icons from Draw.io’s Azure2 SVG library
• Supports 100+ Azure resource types (VMs, App Services, AKS, SQL, etc.)
• Auto-layouts resources left-to-right (data sources on left, destinations on right)
• Groups resources into visual clusters (resource groups, VNets, subnets)
• Creates connections with labels and different line styles (solid, dashed, dotted)
• Auto-opens diagrams in VS Code after generation

Fully Editable Output

Unlike PNG generators, the diagram is just a starting point — customize it however you like:

• Drag icons to reposition — connections auto-route
• Resize groups by dragging edges
• Add labels by double-clicking connections
• Copy/paste icons and groups between diagrams
• Export to PNG, SVG, or PDF when done

Example Output

Generated from a simple prompt: “AKS cluster with Application Gateway, Container Registry, Key Vault, and SQL Database”

Requirements

At a Glance: Python 3.10+, VS Code with the Draw.io extension, and one of: Docker OR the uv package manager.

Required

Recommended (for VS Code integration)

Quick Start

Choose one of three installation methods:

🤔 Not sure? Use Option A (Docker) if you have Docker installed, or Option B if you don’t. Option C is mainly for developers who want to modify this project.

💡 Tip: This project includes a dev container for instant setup - just open in VS Code and select “Reopen in Container”.

⚠️ Configuration Format Note: VS Code uses servers in .vscode/mcp.json, while Claude Desktop uses mcpServers in claude_desktop_config.json. Configuration examples for both are provided below.

📄 VS Code Sample: Copy .vscode/mcp.json.sample to .vscode/mcp.json in your project and uncomment your preferred option.

Option A: Docker (Recommended for Multi-Project Use) 🐳

1. Install Prerequisites:

• Docker Desktop (Windows/Mac | Linux: sudo apt install docker.io)
• VS Code Draw.io Extension: code --install-extension hediet.vscode-drawio

2. Clone and Build:

git clone https://github.com/lilepeeps/Azure-DrawIO-MCP.git
cd Azure-DrawIO-MCP
docker build -t azure-drawio-mcp:latest .

3. Configure MCP Client:

Note: When using Docker, the server automatically translates host paths to the container mount point at /workspace.

Benefits:

• No Python environment management needed
• Works consistently across all your projects
• Easy to update: just rebuild the image

---

Option B: Install from GitHub (Simplest Setup) ⚡

1. Install Prerequisites:

• Python 3.10+
• uv package manager (a fast Python tool runner): pip install uv or winget install astral-sh.uv
• VS Code Draw.io Extension: code --install-extension hediet.vscode-drawio

2. Configure MCP Client:

---

Option C: Local Python Installation

1. Install Prerequisites:

Python 3.10+ is required:

# Windows
winget install Python.Python.3.12

# macOS
brew install [email protected]

# Linux (Ubuntu/Debian)
sudo apt install python3.12 python3.12-venv

VS Code Draw.io Extension:

code --install-extension hediet.vscode-drawio

2. Clone and Install:

git clone https://github.com/lilepeeps/Azure-DrawIO-MCP.git
cd Azure-DrawIO-MCP

# Create virtual environment (recommended)
python -m venv .venv

# Activate virtual environment
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

3. Configure MCP Client:

---

Verify Installation

After configuration, test the MCP server with the following prompt:

Generate an enterprise Azure architecture diagram with:
- Users connecting to Front Door
- Front Door routing to API Management
- API Management connecting to Application Gateway and Service Bus
- Application Gateway load balancing to an AKS Cluster
- Service Bus triggering a Function App
- AKS and Function App both storing data in Cosmos DB
- Function App writing blobs to Storage Account
- Both AKS and Function App retrieving secrets from Key Vault
- Both AKS and Function App sending telemetry to Application Insights

The diagram should be created in your workspace’s diagrams/ folder and open in VS Code.

⚠️ Important: When specifying resource types, use the exact resource_type values from the list_azure_shapes tool. For example, use AzureCosmosDB (not CosmosDB), FunctionApp, and StorageAccount. The tool supports aliases, but exact types ensure correct icon rendering.

---

Usage Examples

This MCP server supports multiple ways to generate Azure architecture diagrams:

🎯 Method 1: Natural Language Prompts

In VS Code with GitHub Copilot, describe what you want:

Generate an Azure architecture diagram showing an AKS cluster with Application Gateway, 
Container Registry, Key Vault, and Azure SQL Database

The AI will interpret your request and call the MCP server with the appropriate resources.

📂 Method 2: Scan Existing Repository

Already have Azure infrastructure in your project (Bicep, Terraform, ARM templates)? Use the included prompt file to help Copilot discover your resources:

How to use it:

1. Open GitHub Copilot chat in VS Code
2. Click the 📎 attachment icon
3. Select Prompts → generate-architecture
4. Ask: “Analyze my infrastructure code and generate a diagram”

The prompt file (.github/prompts/generate-architecture.prompt.md) tells Copilot what to look for and how to call the diagram generator.

💡 Why a prompt file? GitHub Copilot already understands your code semantically — the prompt file just guides it to focus on Azure resources and call the right MCP tools.

📝 Method 3: Structured JSON Specification

For precise control, provide a full specification. Here’s an enterprise architecture example:

{
  "title": "Enterprise Azure Architecture",
  "resources": [
    {"id": "users", "name": "Users", "resource_type": "User", "x": 100, "y": 300},
    {"id": "frontdoor", "name": "Front Door", "resource_type": "FrontDoor", "x": 250, "y": 300},
    {"id": "apim", "name": "API Management", "resource_type": "APIManagementService", "x": 400, "y": 300},
    {"id": "appgw", "name": "Application Gateway", "resource_type": "ApplicationGateway", "x": 550, "y": 200},
    {"id": "aks", "name": "AKS Cluster", "resource_type": "KubernetesServices", "x": 700, "y": 200},
    {"id": "funcapp", "name": "Function App", "resource_type": "FunctionApp", "x": 700, "y": 400},
    {"id": "cosmos", "name": "Cosmos DB", "resource_type": "AzureCosmosDB", "x": 900, "y": 200},
    {"id": "storage", "name": "Storage Account", "resource_type": "StorageAccount", "x": 900, "y": 400},
    {"id": "keyvault", "name": "Key Vault", "resource_type": "KeyVault", "x": 550, "y": 500},
    {"id": "appinsights", "name": "App Insights", "resource_type": "ManagementgovernanceApplicationInsight", "x": 700, "y": 600},
    {"id": "servicebus", "name": "Service Bus", "resource_type": "ServiceBus", "x": 550, "y": 400}
  ],
  "connections": [
    {"label": "HTTPS", "source": "users", "target": "frontdoor"},
    {"label": "Route", "source": "frontdoor", "target": "apim"},
    {"label": "API Calls", "source": "apim", "target": "appgw"},
    {"label": "Async", "source": "apim", "target": "servicebus"},
    {"label": "Load Balance", "source": "appgw", "target": "aks"},
    {"label": "Trigger", "source": "servicebus", "target": "funcapp"},
    {"label": "Data", "source": "aks", "target": "cosmos"},
    {"label": "Blob", "source": "funcapp", "target": "storage"},
    {"label": "Data", "source": "funcapp", "target": "cosmos"},
    {"label": "Secrets", "source": "aks", "target": "keyvault"},
    {"label": "Secrets", "source": "funcapp", "target": "keyvault"},
    {"label": "Telemetry", "source": "aks", "target": "appinsights"},
    {"label": "Telemetry", "source": "funcapp", "target": "appinsights"}
  ],
  "groups": [
    {"id": "networking", "name": "Networking"},
    {"id": "compute", "name": "Compute"},
    {"id": "data", "name": "Data Services"}
  ],
  "open_in_vscode": true
}

💡 Tip: Use list_azure_shapes to discover available resource types. For example, Cosmos DB is AzureCosmosDB, not CosmosDB.

---

Tips for Better Diagrams

The MCP server validates your input and provides guidance:

Common Resource Types

⚠️ Use exact resource types from list_azure_shapes for reliable icon rendering. Aliases may work but exact types are guaranteed.

---

Editing Generated Diagrams

Generated diagrams include instruction text at the top. Here’s how to customize:

1. Move Resources: Click and drag any icon — connections auto-route
2. Resize Groups: Drag group edges to make room
3. Move Groups: Click the group header to drag the entire group
4. Add Labels: Double-click a connection to add descriptive text
5. Reroute Arrows: Click a connection and drag the waypoints
6. Copy/Paste: Ctrl+C/V works for icons and groups
7. Add Resources: Drag Azure icons from the shapes panel

The layout is designed for A4 landscape export.

---

MCP Tools

generate_diagram

Creates a Draw.io diagram from a structured specification.

Parameters:

• title (required): Diagram title
• resources (required): List of Azure resources
  • Each resource can include an optional rationale field for the legend
• connections: List of connections between resources
• groups: Optional resource groups/clusters
• workspace_dir: Where to save the diagram
• filename: Output filename (without .drawio extension)
• open_in_vscode: Open the diagram in VS Code after generation (default: false)
• show_legend: Show a numbered legend table at the bottom (default: true)
• use_infinite_canvas: Use infinite canvas instead of fixed A4 page (default: false)
  • When true: Creates an expandable canvas that grows with content (recommended for complex diagrams)
  • When false: Uses fixed A4 landscape page for consistent printing/export

Example:

{
  "title": "Web Application Architecture",
  "resources": [
    {"id": "fd", "resource_type": "FrontDoor", "name": "Azure Front Door", "rationale": "Global load balancing and CDN"},
    {"id": "app", "resource_type": "AppService", "name": "Web App", "rationale": "Hosts the React frontend"},
    {"id": "sql", "resource_type": "SQLDatabase", "name": "Azure SQL", "rationale": "Managed relational database"}
  ],
  "connections": [
    {"source": "fd", "target": "app"},
    {"source": "app", "target": "sql"}
  ],
  "open_in_vscode": true,
  "show_legend": true
}

list_azure_shapes

Lists all available Azure resource types organized by category.

Categories:

• compute: VM, AKS, AppService, FunctionApp, ContainerInstances
• network: VNet, LoadBalancer, ApplicationGateway, Firewall, VPNGateway
• storage: StorageAccount, BlobStorage, DataLake, ManagedDisk
• database: SQLDatabase, CosmosDB, Redis, MySQL, PostgreSQL
• web: APIM, SignalR, StaticWebApp
• security: KeyVault, EntraID, Sentinel, SecurityCenter
• integration: ServiceBus, EventHub, EventGrid, LogicApp, DataFactory
• ai: AzureOpenAI, CognitiveServices, MachineLearning, AISearch
• analytics: Synapse, Databricks, StreamAnalytics, PowerBI
• devops: DevOps, Monitor, LogAnalytics, AppInsights
• iot: IoTHub, IoTCentral, DigitalTwins
• general: User, Client, Browser, OnPremise, Internet

get_diagram_examples

Returns example diagram specifications you can use as templates.

Types: azure, network, compute, data, integration, security, all

---

Optional: scan_workspace

Note: For GitHub Copilot users, the prompt file approach is recommended. Copilot’s semantic understanding is more accurate than regex-based scanning.

For non-Copilot MCP clients (Claude Desktop standalone, etc.), scan_workspace provides basic resource discovery:

Parameters:

• workspace_dir (required): Path to scan
• generate_diagram: Auto-generate diagram (default: true)
• filename: Output filename
• open_in_vscode: Open in VS Code after generation

Scans for: Bicep (*.bicep), Terraform (*.tf), ARM templates, Azure SDK usage patterns.

Opening Generated Diagrams

Automatic Opening (Recommended)

Set open_in_vscode: true when generating diagrams and they’ll open automatically in VS Code. Requires:

• VS Code installed with code command in PATH
• Draw.io extension: hediet.vscode-drawio

VS Code Manual

1. Install the Draw.io extension: hediet.vscode-drawio
2. Open the generated .drawio file
3. Edit directly in VS Code!

Draw.io Desktop/Web

1. Download Draw.io: https://www.drawio.com/
2. Open → Select your .drawio file
3. Edit and export as needed

Example Prompts for GitHub Copilot

Generate a hub-spoke network architecture with Azure Firewall in the hub 
and AKS clusters in the spokes

Create a serverless event-driven architecture using Event Hubs, 
Azure Functions, and Cosmos DB

Design a zero-trust architecture with Entra ID, Application Gateway with WAF, 
Private Endpoints, and Microsoft Sentinel for monitoring

Project Structure

azure-drawio-mcp/
├── .github/
│   ├── instructions/
│   │   └── drawio.instructions.md   # Best practices for diagram specifications
│   └── prompts/
│       └── generate-architecture.prompt.md  # Prompt for codebase scanning
├── azure_drawio_mcp_server/
│   ├── __init__.py           # Package initialization
│   ├── server.py             # MCP server that handles AI assistant requests
│   ├── drawio_generator.py   # Creates .drawio files using drawpyo library
│   ├── azure_shapes.py       # Azure resource type mappings and styles
│   ├── scanner.py            # Workspace scanner (optional)
│   ├── validator.py          # Draw.io file validation module
│   └── models.py             # Data models for requests/responses
├── diagrams/                 # Generated diagram output directory
├── .dockerignore             # Docker build exclusions
├── Dockerfile                # Container image definition
├── pyproject.toml            # Python package metadata and dependencies
├── requirements.txt          # Python dependencies (pip)
├── README.md                 # This file
└── LICENSE                   # MIT License

---

Validation

Generated diagrams are automatically validated to ensure they can be opened in Draw.io without errors.

The validation checks for:

• XML Declaration: Proper `` header
• Root Structure: Required root cells with id="0" and id="1"
• Unique IDs: No duplicate cell IDs
• Parent References: All parent references point to existing cells
• Edge Integrity: Source and target references on connections are valid
• Geometry: Proper placement and sizing attributes

You can also validate existing diagrams programmatically:

from azure_drawio_mcp_server import validate_drawio_file, format_validation_result

result = validate_drawio_file("path/to/diagram.drawio")
print(format_validation_result(result))

Dependencies

This project uses three Python libraries (installed automatically):

• drawpyo: Creates Draw.io files programmatically
• mcp[cli]: Enables communication with AI assistants
• pydantic: Handles data validation

No Graphviz installation required! 🎉

Troubleshooting

Diagram not created?

• Check that workspace_dir is a valid, writable path
• Look for errors in the MCP server output

Can’t open .drawio file in VS Code?

• Install the Draw.io extension: code --install-extension hediet.vscode-drawio
• Restart VS Code after installation

MCP server not responding?

• Verify Python path in your MCP configuration
• Check that all dependencies are installed: pip install -r requirements.txt
• Ensure the cwd path points to the project root

License

MIT License - See LICENSE file.

Acknowledgments

• Original Inspiration: dminkovski/azure-diagram-mcp - PNG diagram generation using the diagrams package
• Draw.io Generation: MerrimanInd/drawpyo - Python library for creating Draw.io files
• Validation Patterns: drawio-ninja - Best practices for reliable Draw.io XML generation
• VS Code Integration: hediet.vscode-drawio - Draw.io editor for VS Code