| name | drawio-mcp-diagramming |
| description | Create and edit architecture diagrams using Draw.io MCP (`drawio/create_diagram`) with reliable Azure and AWS icon rendering guidance and troubleshooting. Supports Azure2 and AWS4 icon libraries. Requires Python 3 and internet access to refresh icon catalogs (periodic, not per-run). |
| metadata | {"author":"Thomas Thornton","version":"1.0.0","last-updated":"2026-05-19"} |
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.
- The user asks for an auth or identity flow (OAuth 2.0, OIDC, JWT validation, SSO, login, token exchange, Entra, Cognito).
- The user asks for an API or microservice interaction diagram (request/response chain, service-to-service calls, API gateway flow).
- The user asks for a CI/CD pipeline or deployment workflow (build, test, deploy stages, GitHub Actions, Azure DevOps, approval gates).
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
- Identify the cloud provider — determine whether the diagram uses Azure, AWS, or both (multi-cloud).
- 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.
- If diagram uses neither Azure nor AWS icons — or is a sequence or flow diagram (auth flow, API call chain, CI/CD pipeline): skip icon lookup. For sequence and flow diagrams, apply Sequence and Flow Diagram Patterns (see section below).
- 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 network isolation explanation box
- 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
- Build a valid
mxGraphModel payload using verified icons when applicable.
- Call
drawio/create_diagram with the XML.
- If user wants a file artifact, save as
.drawio wrapped in <mxfile><diagram>...</diagram></mxfile>.
- Keep labels concise and explicit (service name + role).
- 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.
- Animated flow on connectors: adding
flowAnimation=1; to any edge style renders a moving dot that travels along the arrow, making directional flow immediately visible without extra labels — ideal for data-flow and pipeline diagrams. The animation is preserved in SVG export and the draw.io desktop app. By default, ask the user whether they want any flow arrows animated before generating the diagram — "Would you like any of the flow arrows animated to show traffic direction? If so, which ones?" Apply flowAnimation=1; only to the edges the user identifies. If the user has already indicated they want a static/clean diagram, skip the question.
- 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, using this colour palette:
- HTTPS:443 — Azure blue (
#0078D4, thick solid) for internet ingress; prominent but professional
- HTTP:80/8080/8090/8095 — Teal (
#00897B, solid) for backend pool traffic; signals allowed/healthy east-west flow
- PostgreSQL:5432 — Indigo (
#5C6BC0, dashed) for database connections; purple/indigo conventionally marks the data tier
- NFS/Gluster — Green (
#43A047, solid) for shared storage flows
- RBAC/Identity/SMTP — Amber (
#F57C00, dashed) for management/control-plane traffic
- Denied/Blocked (WAF, NSG deny rules) — Red (
#C62828) — reserve red exclusively for blocked or denied traffic
- Use
edgeStyle=orthogonalEdgeStyle for clean routing
- Include
<Array> waypoints for complex routing
- Direction animation on key edges:
flowAnimation=1; adds a moving dot along a connector arrow, making ingress paths, egress routes, and replication flows readable at a glance — the effect renders in SVG export and draw.io desktop and works on any edge style. Before generating the diagram, ask the user: "Would you like any of the traffic arrows animated to show flow direction? If so, which ones?" Apply flowAnimation=1; only to the edges they identify. Example style for an animated internet ingress arrow: style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;strokeWidth=3;strokeColor=#0078D4;"
Essential Components
Include two annotation boxes in every Azure topology diagram:
- Network Isolation Explanation (top-left,
fillColor=#fff9cc) — visual conventions: VNet thick borders, subnet dashed borders, NSG/DNS notes
- Zone Separation — VNet Peering zone (grey
fillColor=#f5f5f5) and External Services zone (orange fillColor=#ffe6cc)
For a complete example, see references/topology-patterns.md.
Professional Topology Checklist (Azure)
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 and ports, using the same colour palette as Azure:
- HTTPS:443 (internet ingress) — Azure blue (
#0078D4, thick solid) for external traffic entering via ALB/CloudFront
- HTTP:80→HTTPS redirect — Teal (
#00897B, solid) for healthy/redirected traffic
- Port 5432/3306 — Indigo (
#5C6BC0, dashed) for database connections
- HTTPS:443 (internal AWS service calls) — Green (
#43A047, solid) for traffic to VPC Endpoints and AWS-managed services (S3, SSM, Secrets Manager, etc.)
- SSH:22 / SSM — Amber (
#F57C00, dashed) for management / Bastion access
- Denied/Blocked (WAF, Security Group deny rules) — Red (
#C62828) — reserve red exclusively for blocked traffic
- Use
edgeStyle=orthogonalEdgeStyle for clean routing
- Show NAT Gateway path for private subnet → internet egress
- Direction animation on key edges:
flowAnimation=1; adds a moving dot along a connector arrow, making ingress paths, egress routes, and data-transfer flows readable at a glance — the effect renders in SVG export and draw.io desktop and can be applied to any edge style. Before generating the diagram, ask the user: "Would you like any of the traffic arrows animated to show flow direction? If so, which ones?" Apply flowAnimation=1; only to the edges they identify. Example style for an animated ingress path: style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;strokeWidth=3;strokeColor=#0078D4;"
Essential Components
Include two annotation boxes in every AWS topology diagram:
- Network Isolation Explanation (top-left) — visual conventions: VPC thick borders, subnet tiers (public/private/isolated), SG/NACL notes, VPC Endpoints
- Zone Separation — Internet/Edge zone (orange), VPC Peering/Transit Gateway zone (grey), AWS Managed Services zone (purple)
For a complete example, see references/topology-patterns.md.
Professional Topology Checklist (AWS)
Sequence and Flow Diagram Patterns
Use this section for diagrams that show temporal flows — what happens in order — rather than infrastructure topology. No cloud icon catalog lookup is required.
When to Apply
| Diagram type | Keywords | Layout |
|---|
| Auth / authorisation flow | OAuth, OIDC, JWT, SSO, login, token exchange, Entra, Cognito | Swimlane interaction flow |
| API / microservice call chain | REST, GraphQL, request/response, service-to-service, API gateway | Swimlane or vertical flowchart |
| CI/CD pipeline | pipeline, build, deploy, release, GitHub Actions, Azure DevOps, approval gate | Horizontal pipeline flowchart |
Layout Approach
Swimlane interaction flow (auth / API flows with 2–5 actors):
- Represent each actor as a labelled header rectangle at the top, with a matching full-height light-coloured background column below it
- Steps flow top-to-bottom within each column; number them (
1., 2., 3.) in the label so execution order is unambiguous
- All step boxes and edges live at
parent="1" (root) — no nested swimlane cell geometry required
- Edges cross between columns with
edgeStyle=orthogonalEdgeStyle;
- Canvas:
pageWidth="1400" pageHeight="900" for 3 actors; add ~420 px width per additional actor
Horizontal pipeline flowchart (CI/CD):
- Stages flow left-to-right: Source → Build → Test → Staging → Approval → Production
- Use
rounded=1 rectangles for stages, rhombus shape for gate / decision points
- Colour-code each stage box using the Stage Colours table below
- Failure branch goes downward from the gate with a red edge to a Rollback/Notify step
- Canvas:
pageWidth="1700" pageHeight="600"
Colour Conventions
Edge colours (consistent with topology palette):
| Meaning | strokeColor | Style |
|---|
| Primary request / call | #0078D4 Azure blue | solid, strokeWidth=2 |
| Success response / return | #00897B Teal | solid, strokeWidth=2 |
| Token / credential / redirect | #F57C00 Amber | dashed=1, strokeWidth=2 |
| Async / event-driven call | #5C6BC0 Indigo | dashed=1, strokeWidth=2 |
| Error / rejection / rollback | #C62828 Red | solid, strokeWidth=2 |
| Optional / conditional | #666666 Grey | dashed=1, strokeWidth=1 |
Participant lane colours (swimlane header + column background at opacity=30):
| Actor type | fillColor | strokeColor |
|---|
| User / browser / client | #dae8fc | #6c8ebf |
| Identity provider (Entra, Cognito, Okta) | #e6f4ea | #82b366 |
| API / backend service | #fff3e0 | #e6821e |
| Database / data store | #f5f5f5 | #666666 |
| Cloud managed service (Key Vault, S3, etc.) | #f3e5f5 | #7B1FA2 |
Stage fill colours (CI/CD pipeline):
| Stage | fillColor | fontColor |
|---|
| Source / Trigger | #0078D4 | #ffffff |
| Build | #00897B | #ffffff |
| Test / Quality Gate | #F57C00 | #ffffff |
| Deploy to Staging | #5C6BC0 | #ffffff |
| Approval Gate | #795548 | #ffffff |
| Deploy to Production | #43A047 | #ffffff |
| Rollback / Failure | #C62828 | #ffffff |
Flow Animation
flowAnimation=1; works on sequence/flow edges exactly as in topology diagrams. Apply to primary call paths or pipeline stage transitions. Always ask the user before applying.
Checklist (Sequence/Flow Diagrams)
Icon Reference Assets (Azure Diagrams)
This section applies only when the diagram includes Azure services/icons.
- 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.
- 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.
- Render review fallback
- If diagram review shows wrong/missing icon rendering, grep the catalog for alternative paths.
- Substitute and regenerate the diagram.
- 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:
-
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;
-
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.
- 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.
- 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.
- Render review fallback
- If diagram review shows wrong/missing shape rendering, grep the catalog for alternative names.
- Substitute and regenerate the diagram.
- 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:
-
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)
-
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:
grep -i "gateway" references/azure2-complete-catalog.txt
grep -i "lambda" references/aws4-complete-catalog.txt
Use verified paths in cell styles:
- Azure:
image;aspect=fixed;html=1;points=[];align=center;image=img/lib/azure2/<category>/<Icon_Name>.svg;
- AWS:
shape=mxgraph.aws4.<shape_name>;fillColor=<service_color>;fontColor=#ffffff;strokeColor=none;
See references/REFERENCE.md for absolute URL fallback, additional grep examples, and known-good icon style strings.
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.
Exporting Diagrams
| Format | How | Notes |
|---|
| SVG | File → Export As → SVG | Recommended — preserves flowAnimation moving-dot effects and all icon rendering. Use for sharing or embedding. |
| PNG | File → Export As → PNG | Static snapshot. flowAnimation effects are not captured; icons and colours are preserved. |
| PDF | File → Export As → PDF | Best for printed or document-embedded diagrams. Static only. |
| .drawio file | File → Save As | Preserves all XML, animation settings, and style attributes for future editing. |
flowAnimation=1 is only visible when the diagram is open in draw.io desktop or rendered as SVG. It does not appear in PNG or PDF exports — inform the user of this if they ask why the animation isn't showing.
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
- All icon paths confirmed against the relevant static catalog before calling
drawio/create_diagram; unconfirmed icons are not used
- Diagram renders correctly; XML is valid and opens in draw.io
- Cloud resources identifiable via correct icons and clear labels
- All applicable topology checklist items passed (borders, subnets, traffic labels, legend, isolation box, zones, canvas size)
- All applicable sequence/flow checklist items passed (numbered steps, colour-coded edges, error paths, canvas size)
- Animation preference confirmed;
flowAnimation=1; applied only to user-identified edges
- File artifact saved as
.drawio (wrapped in <mxfile>) if requested
- Layout anti-patterns checked against references/layout-antipatterns.md before finalising
