AWS Builder Center
Generating AWS Architecture Diagrams with Kiro IDE

Generating AWS Architecture Diagrams with Kiro IDE

Kiro IDE is an AI-powered development environment that can generate AWS architecture diagrams from plain English descriptions. By configuring MCP (Model Context Protocol) servers, Kiro's agent connects to specialized AWS tools that validate designs against best practices and render professional diagrams - no manual drag-and-drop required.

Founder | Multi-Cloud Engineer | Building System and Engineers
Kiro IDE is an AI-powered development environment that can generate AWS architecture diagrams from plain English descriptions. By configuring MCP (Model Context Protocol) servers, Kiro's agent connects to specialized AWS tools that validate designs against best practices and render professional diagrams - no manual drag-and-drop required.
This guide covers prerequisites, MCP server configuration, and practical prompts for generating three common architecture patterns directly from Kiro's Agent panel.

How It Works

Kiro IDE uses two MCP servers working in tandem:
MCP Server
Role
awslabs.aws-documentation-mcp-server
Validates your design intent against official AWS documentation and best practices before any diagram is generated
awslabs.aws-diagram-mcp-server
Generates diagram code (using Python's diagrams package) and renders it to PNG/SVG via Graphviz
The workflow follows three stages:
  1. Intent capture - you describe your architecture in Kiro's Agent panel
  1. Tool orchestration - Kiro consults the Documentation server to validate the design, then the Diagram server generates and runs the visualization code
  1. Output - a rendered image file is saved to your working directory

Prerequisites

Before starting, ensure you have:
  • macOS, Linux, or Windows with WSL
  •  brew  (macOS) or  apt  (Linux/WSL) package manager
  • Internet access for  uvx  to fetch MCP servers on first run

Step 1: Install Python Runtime (via  uv )

The Diagram MCP server uses  uv  to manage its Python environment.
# macOS
brew install uv

# Linux / WSL
pip install uv

Then install a compatible Python version:
uv python install 3.13

Note: Python 3.10 or higher is required. Python 3.13 is recommended for best compatibility with the  diagrams  package.

Step 2: Install Graphviz

Graphviz is the rendering engine that converts diagram code into visual output. It must be installed at the OS level.
# macOS
brew install graphviz

# Ubuntu / Debian / WSL
sudo apt-get install -y graphviz

Verify Graphviz is on your  PATH :
dot -V


Step 3: Configure MCP Servers in Kiro IDE

Kiro IDE discovers MCP servers from a local JSON configuration file at  ~/.kiro/settings/mcp.json .
Create the file if it doesn't exist:
# macOS / Linux / WSL
mkdir -p ~/.kiro/settings
nano ~/.kiro/settings/mcp.json

Paste the following configuration:
{
"mcpServers": {
"awslabs.aws-documentation-mcp-server": {
"command": "uvx",
"args": ["awslabs.aws-documentation-mcp-server@latest"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" },
"autoApprove": [],
"disabled": false
},
"awslabs.aws-diagram-mcp-server": {
"command": "uvx",
"args": ["awslabs.aws-diagram-mcp-server"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR" },
"autoApprove": [],
"disabled": false
}
}
}

Save and exit ( Ctrl+O ,  Enter ,  Ctrl+X  in nano).

What each field does

Field
Description
command
Uses uvx to run the MCP server in an isolated Python environment
args
The PyPI package name of the MCP server
env.FASTMCP_LOG_LEVEL
Suppresses verbose logs; set to DEBUG for troubleshooting
disabled
Set to true to temporarily disable a server without removing it

Step 4: Verify MCP Servers are Active

  1. Open Kiro IDE
  1. Navigate to Settings → MCP Servers (or check the MCP panel in the sidebar)
  1. Both servers should appear with a green active indicator
If a server shows as inactive, check that  uvx  is on your  PATH  and that the JSON in  mcp.json  is valid (no trailing commas).

Step 5: Validate the Full Pipeline

Open the Agent panel in Kiro IDE and paste this prompt to confirm everything works end to end:
Create a diagram illustrating the secure "Private S3 Access" pattern.
Show the complete traffic flow from an Internet Gateway and Route Table,
through a Subnet protected by Network ACLs, to an EC2 instance.
The EC2 instance must access the S3 bucket using a VPC Gateway Endpoint
to keep traffic on the AWS private network.
Check AWS documentation to ensure it adheres to best practices before
creating the diagram.

Kiro will ask you to approve each tool call. Once approved, it sequences through documentation lookup, code generation, and rendering. A PNG or SVG file saved to your project directory confirms your setup is working.

Generating Diagrams

Open the Agent panel in Kiro IDE and paste any of the prompts below. Specify your preferred output format in the prompt itself (SVG is recommended for documentation; PNG for presentations).

Example 1: Highly Available Web Application

Create a detailed AWS architecture diagram for a highly available web application
and save it as web-ha-architecture.svg.

Requirements:
- VPC with two Availability Zones.
- Public subnets for ALB and NAT Gateway.
- Private subnets for EC2 and RDS (Multi-AZ).
- ALB distributes traffic to two EC2 instances.
- EC2 communicates with RDS securely.
- Include IGW, security groups, and traffic flow arrows.
- Clearly separate presentation, application, and database tiers.

Check AWS documentation to confirm this follows best practices before generating.

What Kiro generates: A VPC boundary with two AZs, the ALB in public subnets routing to EC2 instances in private subnets, and those instances connecting to a Multi-AZ RDS deployment in isolated database subnets. Traffic flow arrows and security group annotations are included automatically.

Example 2: Three-Tier Architecture with ECS and Aurora

Create a detailed AWS 3-tier architecture diagram and save it as
three-tier-architecture.svg.

VPC:
- Two AZs with public and private subnets.
- IGW and NAT Gateways.

Presentation Tier:
- CloudFront distribution.
- ALB in public subnets.

Application Tier:
- ECS Fargate running microservices in private subnets.
- ECS tasks pull images from ECR.

Data Tier:
- Aurora PostgreSQL Multi-AZ in private subnets.

Networking:
- CloudFront to ALB to ECS to Aurora.
- Show security group relationships and subnet groupings.

Check AWS documentation to confirm this follows best practices before generating.

What Kiro generates: A layered diagram showing CloudFront at the edge, the ALB bridging public subnets, ECS Fargate tasks in private subnets with ECR pull access, and the Aurora cluster in isolated database subnets. Security group relationships are represented as labeled connections.

Example 3: Data Processing Pipeline

Create a data processing pipeline diagram using AWS services and save it as
data-pipeline-architecture.svg.

Four clusters:
1. Data Ingestion — Kinesis Data Streams
2. Data Processing — Lambda, AWS Glue
3. Data Storage — S3 buckets (Raw, Processed, Curated)
4. Analytics — QuickSight

Include:
- Data flow arrows between each stage.
- IAM role boundaries.
- Regional grouping.

Follow AWS best practice visualization.
Check AWS documentation before generating.

What Kiro generates: A left-to-right pipeline diagram grouping services into four logical clusters. Arrows represent data movement from Kinesis through Lambda/Glue processing, into tiered S3 storage, and finally into QuickSight for visualization.

MCP Tool Reference

The Diagram MCP server exposes three tools Kiro uses internally:
Tool
Description
list_icons
Lists available icons from the diagrams package, organized by AWS service category
get_diagram_examples
Returns boilerplate Python code for common diagram types
generate_diagram
Executes Python diagram code and renders the output image
The Documentation MCP server exposes:
Tool
Description
search_documentation
Searches the official AWS Documentation Search API
read_documentation
Fetches and converts an AWS documentation page to Markdown for in-context validation
recommend
Returns related content recommendations for a given documentation page

Output and Integration

Diagrams generated by Kiro include both the rendered image and the underlying Python source file. This means you can:
  • Version-control diagrams by committing the  .py  source alongside application code
  • Update diagrams by editing the Python file and asking Kiro to re-render, rather than rebuilding from scratch
  • Integrate into CI/CD by triggering diagram regeneration whenever infrastructure definitions change
  • Export to multiple formats by asking Kiro to re-render the same source as  .svg ,  .png , or  .pdf 

Troubleshooting

Symptom
Likely cause
Fix
MCP servers not listed in Kiro
mcp.json path or syntax error
Validate JSON at ~/.kiro/settings/mcp.json; check for trailing commas
dot: command not found during rendering
Graphviz not on PATH
Re-install Graphviz and restart Kiro IDE
uv: command not found
uv not installed or not on PATH
Run brew install uv or pip install uv and restart Kiro
Diagram renders but icons are missing
Network access blocked to icon CDN
Check firewall/proxy settings; ensure outbound HTTPS is permitted
Kiro prompts tool approval on every run
autoApprove is empty
Add specific tool names (e.g. "generate_diagram") to the autoApprove array in mcp.json
Server shows inactive after config change
Kiro hasn't reloaded MCP config
Restart Kiro IDE or use the MCP panel reload option

Key Concepts Summary

  • Kiro IDE is an AI-powered development environment whose Agent panel can orchestrate MCP tool calls to produce outputs from natural language.
  • MCP (Model Context Protocol) is an open standard for connecting AI agents to external servers, data sources, and APIs.
  • The Documentation MCP server validates architectural intent against AWS best practices before any code is generated.
  • The Diagram MCP server generates both Python source code and rendered images, enabling reproducibility and version control.
  • Graphviz is the underlying rendering engine and must be installed at the OS level for diagram output to work.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article