Create AWS architecture diagrams using Kiro CLI
A common development bottleneck is the rapid obsolescence of architecture diagrams after a new service is deployed. Even with a well-defined initial design, routine changes such as adding security groups or modifying data flows can render diagrams unreliable within a matter of days. This documentation drift slows triage, onboarding, and audits, and accumulates as a less visible form of technical debt.
What if your diagram were auto-generated, updated instantly, and validated against best practices? Introducing Kiro CLI and the Model Context Protocol (MCP) as the system to generate diagrams automatically from live context, making infrastructure self-documenting.
The Kiro CLI can understand natural language and generate outputs; it alone cannot ensure that diagrams are both accurate and visually precise. Integrating it with specialized MCP servers enables the system to validate the design against AWS best practices and automatically produce a diagram. This approach directly addresses documentation drift by keeping diagrams always aligned with live architectural intent.
The architectural visualization bridge#
The ability to turn natural language into a perfectly styled, technically validated architecture diagram relies on extending Kiro CLI’s core intelligence through local agents. This bridge is built on specialized MCP servers.
Specialized knowledge on demand#
The visualization process relies on the collaboration of two distinct, powerful agents:
AWS Documentation MCP server: This server serves as a real-time knowledge source to ensure the design is sound before code generation. It validates the user’s design intent against AWS best practices referenced from official documentation, thereby preventing common architectural pitfalls such as poor security grouping or lack of redundancy.
AWS Diagram MCP server: Once the design intent is approved and validated, this server generates the visualization both as Python code and as a rendered image (PNG/SVG) using the standard Python
diagramspackage. The code allows reproducibility, modification, and integration into pipelines, while the image provides an immediate visual reference. It handles all the complex styling, icon fetching, and layout logic for the best-practice-compliant architecture.
From query to visual output#
The complex process of design and rendering is distilled into a simple, three-step conversation:
Intent capture (Prompt): The user describes the architecture in natural language (e.g., “Create a high availability API backend with private database access and S3 storage.”). This is where the user’s high-level intent is captured, without needing to know the underlying icons, code, or layout rules.
Tool orchestration: Kiro CLI first consults the Documentation MCP server to validate the user’s intent against AWS best practices (e.g., should the database be private? Is a WAF recommended?). Once validated, the Diagram MCP server generates Python diagram code based on the approved architecture, producing a blueprint that is technically sound and ready for rendering.
Execution and generation: The Diagram MCP server runs the validated Python code using the GraphViz renderer to output the final, best-practice-compliant diagram image (PNG/SVG).
Setting up your diagramming workspace#
To enable this powerful generative workflow, you need to configure your local environment with the necessary dependencies and connect the two specialized MCP servers.
Core dependencies#
The Diagram MCP server has a small but important set of prerequisites to handle the code execution and rendering:
Python tool manager and Python 3.10+#
To install the uv, which is a Python tool manager, execute the following command in the terminal.
brew install uv
After installing the uv, use it to install the required Python runtime. To do this, execute the following command:
uv python install 3.13
GraphViz#
The external rendering engine required by the diagrams package must be installed separately on your operating system. If it is not already installed, please refer to the official GraphViz documentation for installation instructions.
Enable and configure MCP servers#
Now that your local dependencies are ready, the next crucial step is to enable the specialized MCP servers. These servers serve as the local communication bridge, providing the generative AI model with the necessary tools to draw diagrams and consult documentation.
Note: Ensure that the Kiro CLI is already installed on your local system.
Before enabling them, you’ll need to create the required local configuration structure.
Create the configuration blueprint#
The mcp.json file is a local configuration blueprint that informs the Kiro CLI exactly which Model Context Protocol (MCP) servers should be loaded and activated in your environment.
Create the required directory structure: Start by creating the
~/.aws/amazonqdirectory using this command:
mkdir -p ~/.aws/amazonq
Create the configuration file: Next, create the
mcp.jsonfile using a terminal editor:
Note: Ensure that your chosen editor, such as nano or vim, is installed on your system.
nano ~/.aws/amazonq/mcp.json
Paste and save the configurations: Paste the following JSON configuration into the file and save the changes. This explicitly defines and enables the two specialized servers:
{"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}}}
By adding these entries, you ensure the Kiro CLI automatically discovers and loads the necessary agents:
awslabs.aws-documentation-mcp-server:Provides real-time access to the official AWS documentation API, enabling Kiro CLI to validate your architectural requests against best practices.awslabs.aws-diagram-mcp-server:Activates the diagram-generation tool, enabling Kiro CLI to produce the visualization in both Python code (for reproducibility) and as a rendered visual output (PNG/SVG) using the Pythondiagramslibrary.
Without this configuration, these powerful community-driven agents remain disabled and cannot be utilized by the Kiro CLI.
Test and validate your generative design bridge#
Once you have configured the mcp.json file and installed the prerequisites, it’s time to test the communication flow. This initial test not only verifies your setup but also demonstrates the powerful, two-pronged approach of validation and visualization at work.
Enter the following command to initialize the Kiro CLI chat interface:
kiro-cli
Run the validation prompt: Use a comprehensive scenario that requires Kiro CLI to reason about network boundaries and security:
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.Crucially, the EC2 instance must access the S3 bucket using a VPC Gateway Endpoint to keep traffic on the AWS private network.Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.
Kiro CLI will ask you to trust the tools (t) at each step of the sequence, and upon execution, it will proceed through documentation lookup, code generation, and diagram rendering.
If you see the final diagram image rendered as shown below, your environment is correctly configured to use the MCP for architecture generation.
Note: Kiro CLI generates diagrams dynamically using AI; your output may vary slightly in layout or styling from the following example. However, the core architectural components and logic will remain consistent.
The conversational architecture design#
The true value of this integration lies in simplifying complex architectural design through conversation. You no longer need to know the specific icons or layout rules; you only need to describe your intent.
When you provide a prompt, the AWS Diagram and Documentation MCP servers complete a seamless, intelligent workflow:
Step | Action | MCP Server Tool Used | Insight Provided to the Architect |
Interpretation | Interpret requirements and identify core components. | Claude Sonnet (Core LLM) | Understands the need for nodes, edges, and clusters. |
Validation | Check for best practices on the official AWS documentation. |
| Ensures the architecture adheres to security and design guidelines. |
Code Generation | Generate Python code using the
package. |
| Translates the validated design into executable code with the latest AWS icons. |
Execution | Execute the code to create the diagram. |
| Produces the final, high-quality image (PNG/SVG) and saves it to a local output directory. |
Real-world architecture use case#
This section showcases the versatility of Kiro CLI by providing a detailed example that illustrates how it handles modern, serverless designs.
Example: Serverless user profile system#
Let’s generate a diagram for a simple, relatable scenario: a serverless backend for a mobile app where users log in and update their profiles.
We will ask Kiro CLI to build this using the three most common AWS serverless building blocks, while ensuring it handles security and monitoring automatically.
Enter the following prompt in the Kiro CLI:
Create a diagram for a serverless user profile system.Users should log in using Amazon Cognito.Once logged in, they send requests to an API Gateway, which triggers a Lambda function to save their profile data into a DynamoDB table.Check for AWS documentation to ensure it adheres to best practices before you create the diagram.
The result is not just a diagram, it’s a validated architecture that Kiro CLI generated in seconds:
The logic behind the design:
The generated diagram visualizes a compliant serverless data flow with clear separation of concerns:
Authentication and authorization (Amazon Cognito): The architecture begins with identity management. Kiro CLI correctly places Cognito at the entry point to handle user sign-up and sign-in, ensuring that only authenticated requests can proceed further.
API management (Amazon API Gateway): This service acts as the RESTful endpoint for the application. It provides a secure interface to the backend, handling request routing, throttling, and integration with the compute layer.
Serverless compute (AWS Lambda): This function contains the business logic. It executes code in response to API events (e.g., “update profile”) and automatically scales capacity to match the number of incoming requests.
NoSQL database (Amazon DynamoDB): The flow concludes with the data persistence layer. DynamoDB provides a low-latency, scalable database for storing user profile information.
Configuration options for customization#
The power of the AWS Diagram MCP Server isn’t just in generation—it’s in control. Through natural language prompts, you can tailor the final output to meet specific documentation or branding needs, eliminating the need for manual editing tools.
Output path control: By default, generated diagrams land in a local
generated-diagramssubdirectory. You can direct Kiro CLI to save the file to a specific project folder or network drive by including a custom file path in your prompt.Vector format flexibility: The standard output format is PNG, a raster format. However, for superior quality and scalability in large documents, you can request vector formats like SVG (Scalable Vector Graphics) directly in your query.
Branding and style customization: You can influence the visual presentation by specifying parameters such as colors, shapes, and layout in your prompt, ensuring the generated diagram immediately aligns with your company or team's established style guide.
Conclusion#
The combination of the AWS Diagram MCP server and the AWS Documentation MCP server transforms architecture documentation from a reactive burden to a proactive, conversational advantage. It shifts the focus from drawing boxes to defining strategic design goals.
This results in a powerful, tangible business impact:
Standardization: Eliminates stylistic fragmentation. Regardless of who creates the diagram, the output always adheres to official AWS icon sets and styling rules, replacing manual drawings with reproducible code.
Shift-left compliance: Architectural best practices are validated by the Documentation MCP server before the diagram is created, preventing mistakes early.
Zero documentation drift: Diagrams reflect the intent and are easy to update, eliminating technical debt.
For more cloud-based learning, explore our latest Cloud Labs:
