Drawio MCP Diagramming

Draw.io MCP Diagramming Skill

Use this skill to create or update diagrams through the Draw.io MCP tool and to avoid common Azure and AWS icon rendering problems.

See references/REFERENCE.md for reference artifacts and refresh commands.

For non-Azure/non-AWS diagrams, you can skip icon discovery/validation scripts and proceed directly to drawio/create_diagram.

When to Use

• The user asks to create or refine architecture diagrams (Azure, AWS, or multi-cloud).
• The user wants draw.io/diagrams.net output from an MCP workflow.
• The user needs Azure service icons in diagrams.
• The user needs AWS service icons in diagrams.
• The user reports that Azure or AWS icons/shapes are not appearing.

Required Tooling

• MCP tool: drawio/create_diagram
• Workspace MCP config should include a drawio server:

{
  "servers": {
    "drawio": {
      "type": "http",
      "url": "https://mcp.draw.io/mcp"
    }
  }
}

Recommended Workflow

1. Identify the cloud provider — determine whether the diagram uses Azure, AWS, or both (multi-cloud).
2. Verify icon paths from the static catalogs — no scripts needed at runtime:
   • Azure: grep references/azure2-complete-catalog.txt
   • AWS: grep references/aws4-complete-catalog.txt
   • Multi-cloud: grep both catalogs as needed.
3. If diagram uses neither Azure nor AWS icons: skip icon lookup and create diagram directly.
4. For Azure infrastructure/network diagrams: apply Professional Network Topology Patterns (see Azure section below):
   • Use larger canvas (1900x1500)
   • VNets with thick borders (strokeWidth=4)
   • Subnets with dashed borders (strokeWidth=2, dashPattern=8 8)
   • Position resources inside their subnets
   • Label all traffic flows with protocols/ports
   • Include traffic legend and network isolation explanation boxes
5. For AWS infrastructure/network diagrams: apply AWS Network Topology Patterns (see AWS section below):
   • Use larger canvas (1900x1500) for multi-VPC/account topologies
   • VPCs with thick borders (strokeWidth=4)
   • Subnets (public/private) with dashed borders (strokeWidth=2, dashPattern=8 8)
   • Position resources inside their respective subnets
   • Label all traffic flows with protocols/ports
   • Include security group / NACL notation
6. Build a valid mxGraphModel payload using verified icons when applicable.
7. Call drawio/create_diagram with the XML.
8. If user wants a file artifact, save as .drawio wrapped in <mxfile><diagram>...</diagram></mxfile>.
9. Keep labels concise and explicit (service name + role).
10. For cloud-specific diagrams, prefer one icon per major service and use edges for flow semantics (ingress/egress/peering/telemetry).

Visual Quality Guardrails

Apply these defaults unless the user explicitly asks for a dense/technical view:

• Use 3-4 major lanes/zones max (for example Source, Pipeline, Cloud target).
• Keep primary flow left-to-right with a single main path.
• Use stage numbering (1, 2, 3, 4) instead of many edge labels.
• Keep one icon per major service; avoid icon-per-step layouts.
• Limit cross-lane dashed lines to one security/auth line and one optional telemetry line.
• Keep text concise (single purpose per box) and avoid multiline overload.
• Prefer a "clean" variant first; add detail only if requested.

For worked examples of common layout problems (stacked edges, repeated labels, observability inside VNet, etc.), see references/layout-antipatterns.md.

Professional Network Topology Patterns (Azure Infrastructure)

When creating Azure infrastructure network diagrams with VNets, subnets, and network isolation:

Canvas Sizing

• Use larger canvas for complex infrastructure: pageWidth="1900" pageHeight="1500"
• Standard canvas may be too small for multi-VNet topologies

VNet and Subnet Visualization

• VNets: Use thick borders (strokeWidth=4) and large containers
  • DMZ VNet: Yellow (fillColor=#fff2cc, strokeColor=#d6b656)
  • Internal VNet: Green (fillColor=#d5e8d4, strokeColor=#82b366)
  • Management Zone: Blue (fillColor=#dae8fc, strokeColor=#6c8ebf)
• Subnets: Use dashed borders (strokeWidth=2, dashed=1, dashPattern=8 8)
  • Position subnet containers inside VNet containers
  • Use lighter shades of parent VNet color
  • Label with subnet name and CIDR (e.g., "Application Subnet - 10.x.2.0/24")
• Delegated Subnets: Add delegation info to label (e.g., "PostgreSQL Subnet - 10.x.4.0/24 (Delegated to Microsoft.DBforPostgreSQL/flexibleServers)")

Resource Positioning

• Position all resources inside their respective subnet containers
• VMs, databases, load balancers must be visually contained within their subnets
• This clearly shows network isolation boundaries

Traffic Flow Visualization

• Label all traffic arrows with protocols and ports:
  • HTTPS:443 (red thick arrows for internet ingress)
  • HTTP:8080/8090/8095 (gold arrows for backend pools)
  • PostgreSQL:5432 (blue dashed arrows for database connections)
  • NFS/Gluster (green arrows for shared storage)
  • RBAC/Identity/SMTP (orange dashed arrows for management/external)
• Use edgeStyle=orthogonalEdgeStyle for clean routing
• Include <Array> waypoints for complex routing

Essential Components

1. Traffic Legend Box (bottom-left)

   • Show all 5 traffic types with color-coded arrows
   • Include protocol/port information
   • Use thick bordered white box (strokeWidth=3)

2. Network Isolation Explanation Box (top-left)

   • Explain visual conventions:
     • "VNets: Thick borders"
     • "Subnets: Dashed borders"
     • "PostgreSQL subnet delegated"
     • "NSGs control traffic"
     • "Private DNS for internal resolution"
   • Use yellow background (fillColor=#fff9cc)

3. Zone Separation

   • VNet Peering Zone: Grey box (fillColor=#f5f5f5, strokeColor=#666666)
   • External Services Zone: Orange box (fillColor=#ffe6cc, strokeColor=#d79b00)

Complete Example Structure

<mxGraphModel pageWidth="1900" pageHeight="1500">
  <!-- VNet Container with thick border -->
  <mxCell id="vnet" value="Internal VNet - 10.x.0.0/16" 
    style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;
    verticalAlign=top;fontSize=16;fontStyle=1;align=center;strokeWidth=4;">
    <mxGeometry x="220" y="580" width="1340" height="820"/>
  </mxCell>
  
  <!-- Subnet Container with dashed border inside VNet -->
  <mxCell id="subnet-app" value="Application Subnet - 10.x.2.0/24"
    style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e6f4ea;strokeColor=#82b366;
    verticalAlign=top;fontSize=13;fontStyle=1;align=center;strokeWidth=2;dashed=1;dashPattern=8 8;">
    <mxGeometry x="260" y="650" width="480" height="340"/>
  </mxCell>
  
  <!-- Resources inside subnet -->
  <mxCell id="vm" style="image;aspect=fixed;html=1;points=[];align=center;
    image=img/lib/azure2/compute/Virtual_Machine.svg;">
    <mxGeometry x="300" y="720" width="64" height="59"/>
  </mxCell>
  
  <!-- Labeled traffic edge -->
  <mxCell id="edge" value="PostgreSQL:5432" 
    style="edgeStyle=orthogonalEdgeStyle;strokeWidth=2;strokeColor=#6c8ebf;dashed=1;"
    edge="1" source="vm" target="postgres">
    <mxGeometry relative="1"/>
  </mxCell>
</mxGraphModel>

Professional Topology Checklist (Azure)

• VNets have thick borders (strokeWidth=4)
• Subnets have dashed borders (strokeWidth=2, dashPattern=8 8)
• All resources positioned inside their subnets
• Traffic arrows labeled with protocols and ports
• Traffic legend box included
• Network isolation explanation box included
• Color-coded zones for different purposes
• Canvas sized appropriately (1900x1500 for complex infra)
• VNet peering connections shown in separate zone
• External services grouped in separate zone

Professional Network Topology Patterns (AWS Infrastructure)

When creating AWS infrastructure network diagrams with VPCs, subnets, and network isolation:

Canvas Sizing

• Use larger canvas for complex infrastructure: pageWidth="1900" pageHeight="1500"
• Standard canvas may be too small for multi-VPC/multi-account topologies

VPC and Subnet Visualization

• VPCs: Use thick borders (strokeWidth=4) and large containers
  • Production VPC: Green (fillColor=#d5e8d4, strokeColor=#82b366)
  • Development VPC: Blue (fillColor=#dae8fc, strokeColor=#6c8ebf)
  • Shared Services VPC: Yellow (fillColor=#fff2cc, strokeColor=#d6b656)
• Subnets: Use dashed borders (strokeWidth=2, dashed=1, dashPattern=8 8)
  • Public Subnets: Light green (fillColor=#e6f4ea, strokeColor=#82b366)
  • Private Subnets: Light blue (fillColor=#EFF7FF, strokeColor=#6c8ebf)
  • Isolated Subnets (databases): Light orange (fillColor=#fff3e0, strokeColor=#e6821e)
  • Position subnet containers inside VPC containers
  • Label with subnet name, AZ, and CIDR (e.g., "Public Subnet A - us-east-1a - 10.x.1.0/24")
• Availability Zones: Use light grey container inside VPC to group subnets per AZ

Resource Positioning

• Position all resources inside their respective subnet containers
• EC2 instances, RDS, Lambda, etc. must be visually contained within their subnets
• Internet-facing resources (ALB, NAT Gateway, Bastion) go in public subnets
• Application servers / ECS tasks go in private subnets
• Databases (RDS, ElastiCache) go in isolated subnets with no outbound internet

Traffic Flow Visualization

• Label all traffic arrows with protocols/ports:
  • HTTPS:443 (red thick arrows for internet ingress via ALB/CloudFront)
  • HTTP:80→HTTPS redirect (light red)
  • Port 5432/3306 (blue dashed arrows for DB connections)
  • HTTPS:443 (green arrows for VPC Endpoints / AWS service calls)
  • SSH:22 / SSM (orange dashed for management / Bastion access)
• Use edgeStyle=orthogonalEdgeStyle for clean routing
• Show NAT Gateway path for private subnet → internet egress

Essential Components

1. Traffic Legend Box (bottom-left)

   • Show all traffic types with colour-coded arrows
   • Include protocol/port information

2. Network Isolation Explanation Box (top-left)

   • Explain visual conventions:
     • "VPCs: Thick borders"
     • "Subnets: Dashed borders (Public/Private/Isolated)"
     • "Security Groups control ingress/egress per resource"
     • "NACLs control subnet-level traffic"
     • "VPC Endpoints for private AWS service access"

3. Zone Separation

   • Internet/Edge Zone: Orange box for CloudFront, Route53, WAF, Shield
   • VPC Peering / Transit Gateway Zone: Grey box
   • AWS Managed Services Zone: Purple box for S3, DynamoDB VPC endpoints, etc.

Complete Example Structure

<mxGraphModel pageWidth="1900" pageHeight="1500">
  <!-- VPC Container with thick border -->
  <mxCell id="vpc" value="Production VPC - 10.x.0.0/16"
    style="rounded=0;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;
    verticalAlign=top;fontSize=16;fontStyle=1;align=center;strokeWidth=4;">
    <mxGeometry x="220" y="200" width="1340" height="1100"/>
  </mxCell>

  <!-- AZ Container inside VPC -->
  <mxCell id="az-a" value="us-east-1a"
    style="rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;
    verticalAlign=top;fontSize=13;align=center;strokeWidth=1;dashed=1;">
    <mxGeometry x="260" y="280" width="600" height="960"/>
  </mxCell>

  <!-- Public Subnet inside AZ -->
  <mxCell id="subnet-public-a" value="Public Subnet A - 10.x.1.0/24"
    style="rounded=1;whiteSpace=wrap;html=1;fillColor=#e6f4ea;strokeColor=#82b366;
    verticalAlign=top;fontSize=12;fontStyle=1;align=center;strokeWidth=2;dashed=1;dashPattern=8 8;">
    <mxGeometry x="280" y="360" width="550" height="200"/>
  </mxCell>

  <!-- ALB stencil shape inside subnet -->
  <mxCell id="alb" value="ALB"
    style="shape=mxgraph.aws4.application_load_balancer;fillColor=#8C4FFF;
    fontColor=#ffffff;strokeColor=none;align=center;html=1;">
    <mxGeometry x="320" y="410" width="64" height="64"/>
  </mxCell>

  <!-- Labeled traffic edge -->
  <mxCell id="edge-rds" value="PostgreSQL:5432"
    style="edgeStyle=orthogonalEdgeStyle;strokeWidth=2;strokeColor=#6c8ebf;dashed=1;"
    edge="1" source="alb" target="rds">
    <mxGeometry relative="1"/>
  </mxCell>
</mxGraphModel>

Professional Topology Checklist (AWS)

• VPCs have thick borders (strokeWidth=4) and are colour-coded by environment
• Subnets have dashed borders (strokeWidth=2, dashPattern=8 8) and are colour-coded by tier (public/private/isolated)
• Availability Zone containers group subnets per AZ
• All resources positioned inside their respective subnets
• Internet Gateway and NAT Gateway shown for public/private egress
• Traffic arrows labeled with protocols and ports
• Security Group boundaries annotated where important
• Traffic legend box included
• Network isolation explanation box included
• Canvas sized appropriately (1900x1500 for complex infra)
• VPC Peering / Transit Gateway shown in separate zone
• Edge/internet services (CloudFront, Route53, WAF) in separate zone

Icon Reference Assets (Azure Diagrams)

This section applies only when the diagram includes Azure services/icons.

1. Use the static catalog — references/azure2-complete-catalog.txt contains all 648 Azure2 icons.
   • Grep it to find icon paths: grep -i "gateway" references/azure2-complete-catalog.txt
   • No HTTP requests or script execution needed at runtime.
2. Hard gate
   • If an icon path cannot be confirmed in the catalog, do not use it in drawio/create_diagram.
   • Find an alternative via grep first.
3. Render review fallback
   • If diagram review shows wrong/missing icon rendering, grep the catalog for alternative paths.
   • Substitute and regenerate the diagram.
4. Refresh catalog (periodic, human-run — not per diagram):

cd .github/skills/drawio-mcp-diagramming/scripts
python3 search_azure2_icons_github.py --max-results 9999 > ../references/azure2-complete-catalog.txt

Azure Icon Caveats (Important)

Azure icon rendering in draw.io can fail for two common reasons:

1. Wrong style type

   • shape=mxgraph.azure2.* may not render in some hosts.
   • Prefer Azure2 image style entries:
   • image;aspect=fixed;html=1;...;image=img/lib/azure2/<category>/<Icon_Name>.svg;

2. Library/environment mismatch

   • Some embedded viewers/extensions do not resolve img/lib/azure2/... consistently.
   • If icons do not render in one host, test in app.diagrams.net.

Icon Reference Assets (AWS Diagrams)

This section applies only when the diagram includes AWS services/icons.

Important difference from Azure: AWS4 icons in draw.io are stencil-based, not individual SVG files. They are referenced using shape=mxgraph.aws4.<name> rather than image=img/lib/aws4/.... The catalog lists ready-to-use style strings in this format.

1. Use the static catalog — references/aws4-complete-catalog.txt contains all 1,037 AWS4 stencil shape names.
   • Grep it to find shapes: grep -i "lambda" references/aws4-complete-catalog.txt
   • Each line is a ready-to-use shape=mxgraph.aws4.* style string.
   • No HTTP requests or script execution needed at runtime.
2. Hard gate
   • If a shape name cannot be confirmed in the catalog, do not use it in drawio/create_diagram.
   • Find an alternative via grep first.
3. Render review fallback
   • If diagram review shows wrong/missing shape rendering, grep the catalog for alternative names.
   • Substitute and regenerate the diagram.
4. Refresh catalog (periodic, human-run — not per diagram):

cd .github/skills/drawio-mcp-diagramming/scripts
python3 search_aws4_icons_github.py --max-results 9999 > ../references/aws4-complete-catalog.txt

AWS Icon Caveats (Important)

AWS4 icon rendering in draw.io can fail for two common reasons:

1. Wrong style approach

   • Do not use image=img/lib/aws4/... — AWS4 icons are stencils, not SVG files.
   • The correct style is: shape=mxgraph.aws4.<name>;fillColor=#E7157B;fontColor=#ffffff;strokeColor=none;
   • Fill colour conventions:
     • Compute (orange): fillColor=#ED7100
     • Storage (green): fillColor=#3F8624
     • Database (blue): fillColor=#C7131F (for Aurora/RDS use red)
     • Networking (purple): fillColor=#8C4FFF
     • Security (red): fillColor=#DD344C
     • Management (orange-red): fillColor=#E7157B
     • General/generic: fillColor=#232F3E (AWS dark)

2. Library/environment mismatch

   • Some embedded viewers may not load the mxgraph.aws4 stencil library.
   • If shapes do not render in VS Code, test in app.diagrams.net.

How to Discover Icons

Grep the static catalogs — no scripts needed at agent runtime:

Azure:

grep -i "gateway" references/azure2-complete-catalog.txt
grep -i "virtual_machine\|load_balancer\|key_vault" references/azure2-complete-catalog.txt

AWS:

grep -i "lambda" references/aws4-complete-catalog.txt
grep -i "load_balancing\|cloudfront\|route_53" references/aws4-complete-catalog.txt

Use verified paths in diagram cell styles:

Azure (SVG image style):

image;aspect=fixed;html=1;points=[];align=center;image=img/lib/azure2/<category>/<Icon_Name>.svg;

AWS (stencil shape style — AWS4 icons are stencils, not SVG files):

shape=mxgraph.aws4.<shape_name>;fillColor=<service_color>;fontColor=#ffffff;strokeColor=none;

For Azure renderer resilience, absolute URLs also work:

image;aspect=fixed;html=1;...;image=https://raw.githubusercontent.com/jgraph/drawio/dev/src/main/webapp/img/lib/azure2/<category>/<Icon_Name>.svg;

If local rendering still fails, open in app.diagrams.net.

See references/REFERENCE.md for known-good Azure2 and AWS4 icon examples.

Fallback Strategy if Icons Still Fail

If Azure or AWS icons still do not render:

• Do not generate the diagram with an unresolved icon set.
• Return the missing icon list and propose verified replacements (grepped from the relevant catalog).
• After replacements validate to OK, then generate the diagram.

Troubleshooting Checklist

• Confirm MCP server appears in MCP: List Servers.
• Run MCP: Reset Cached Tools if tool list is stale.
• Ensure XML is well-formed (no malformed tags or invalid comments).
• Azure: Verify style uses image=img/lib/azure2/... for Azure2 icon mode.
• AWS: Verify style uses image=img/lib/aws4/... for AWS4 icon mode.
• Reopen diagram in web draw.io if VS Code extension rendering differs.
• If an Azure icon path looks wrong, grep references/azure2-complete-catalog.txt for alternatives.
• If an AWS icon path looks wrong, grep references/aws4-complete-catalog.txt for alternatives.
• If either catalog appears stale, re-run the refresh workflow in REFERENCE.md.

Prompt Template for Agents

See references/REFERENCE.md for full example prompt templates.

Definition of Done

• For non-Azure/non-AWS diagrams: diagram is generated and renders correctly.
• For Azure diagrams: all icon paths confirmed against references/azure2-complete-catalog.txt before calling drawio/create_diagram.
• For AWS diagrams: all icon paths confirmed against references/aws4-complete-catalog.txt before calling drawio/create_diagram.
• If render issues found, alternative icon paths sourced from the relevant catalog and substituted.
• Diagram generated via drawio/create_diagram only with confirmed icon paths.
• XML is valid and opens in draw.io.
• Cloud resources are identifiable (icons and clear service labels).
• For Azure infrastructure/network diagrams:
  • VNets use thick borders (strokeWidth=4) and are color-coded
  • Subnets use dashed borders (strokeWidth=2, dashPattern=8 8)
  • All resources positioned inside their respective subnets
  • All traffic flows labeled with protocols and ports
  • Traffic legend box included (bottom-left)
  • Network isolation explanation box included (top-left)
  • Canvas appropriately sized (1900x1500 for complex topologies)
  • VNet peering and external services in separate zones
• For AWS infrastructure/network diagrams:
  • VPCs use thick borders (strokeWidth=4) and are colour-coded by environment
  • Subnets use dashed borders and are colour-coded by tier (public/private/isolated)
  • Availability Zone containers group subnets per AZ
  • All resources positioned inside their respective subnets
  • Internet Gateway and NAT Gateway shown for public/private egress
  • All traffic flows labeled with protocols and ports
  • Traffic legend box included (bottom-left)
  • Network isolation explanation box included (top-left)
  • Canvas appropriately sized (1900x1500 for complex topologies)
  • VPC Peering / Transit Gateway and edge services in separate zones
• Layout anti-patterns checked against references/layout-antipatterns.md before finalising