Streamlining AWS Architecture Diagrams with Amazon Q Developer CLI

Introduction to AWS Architecture Diagrams

Challenges in Traditional Diagramming Methods

Introducing Amazon Q Developer CLI and Model Context Protocol

Solution Overview

Prerequisites for Using the Amazon Q Developer CLI

Setting Up Your Environment

Installing Amazon Q Developer CLI

Configuring MCP Servers

Understanding MCP Server Tools

Testing Your Setup

Configuration Options for Diagram Generation

Creating AWS Architecture Diagrams Effortlessly

Example Diagrams

Example 1: Simple Web Application Architecture

Example 2: Multi-Tier Architecture

Example 3: Serverless Architecture

Example 4: Data Processing Diagram

Real-World Architecture Patterns

Ecommerce Platform Architecture

Intelligent Document Processing Solution

Cleanup Procedures

Conclusion

About the Authors

Streamlining AWS Architecture Diagrams with Amazon Q Developer CLI

Creating professional AWS architecture diagrams is essential for solutions architects, developers, and technical teams. These diagrams facilitate communication with stakeholders, document compliance requirements, and serve as blueprints for implementation teams. However, traditional diagramming methods pose several challenges:

1. Time-Consuming Process: Crafting detailed architecture diagrams manually can take hours or even days.
2. Steep Learning Curve: Mastering specialized diagramming tools requires significant investment in time and effort.
3. Inconsistent Styling: Maintaining visual consistency across multiple diagrams can be challenging.
4. Outdated AWS Icons: Keeping abreast of the latest AWS service icons and best practices can be overwhelming.
5. Difficult Maintenance: Updating diagrams as architectures evolve can become increasingly burdensome.

Enter the Amazon Q Developer CLI with the Model Context Protocol (MCP), providing a streamlined approach to creating AWS architecture diagrams. By leveraging generative AI through natural language prompts, architects can generate professional diagrams in minutes, adhering to AWS best practices.

In this post, we’ll delve into using Amazon Q Developer CLI with AWS Diagram MCP and AWS Documentation MCP servers to create sophisticated architecture diagrams that align with AWS best practices. We’ll cover techniques for creating basic to advanced diagrams, including detailed examples and step-by-step instructions.

Solution Overview

The Amazon Q Developer CLI is a command-line interface that bridges the generative AI capabilities of Amazon Q directly to your terminal. Developers can interact with Amazon Q using natural language prompts, making it an invaluable tool for various development tasks.

Developed by Anthropic as an open protocol, the Model Context Protocol (MCP) connects AI models to virtually any data source or tool. Here’s a quick overview of the MCP architecture:

• Host: Programs requiring data access through the MCP protocol, such as Anthropic’s Claude Desktop or AWS MCP CLI.
• Client: Protocol clients maintaining one-to-one connections with the server.
• Server: Lightweight programs exposing capabilities through standardized MCP or acting as tools.
• Data Sources: Local databases, file systems, or external APIs that MCP servers can connect to.

As of April 2025, MCP allows Amazon Q Developer to work with specialized servers, enhancing capabilities beyond the base model. The AWS Diagram MCP Server enables Amazon Q to generate architecture diagrams using the Python Diagrams package, complete with access to the full AWS icon set and architectural best practices.

Prerequisites

To implement this solution, ensure you have an AWS account with the necessary permissions. Follow the steps below to set up your environment.

Set Up Your Environment

Before creating diagrams, you’ll need to install Amazon Q CLI, the AWS Diagram MCP server, and AWS Documentation MCP server.

Install Amazon Q Developer CLI

1. Download and install Amazon Q Developer CLI by following the instructions provided.
2. Verify the installation with the command:

   q --version

3. Configure Amazon Q CLI with your AWS credentials using:

   q login

Set Up MCP Servers

1. Install uv:

   pip install uv

2. Install Python 3.10 or newer:

   uv python install 3.10

3. Install GraphViz for your OS.
4. Add the servers to your ~/.aws/amazonq/mcp.json file:

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

Amazon Q CLI will automatically discover MCP servers listed in ~/.aws/amazonq/mcp.json.

Understanding MCP Server Tools

The AWS Diagram MCP server provides powerful tools:

• list_icons: Lists available icons from the diagrams package organized by service category.
• get_diagram_examples: Provides example code for various diagram types (AWS, sequence, flow, etc.).
• generate_diagram: Creates a diagram from Python code using the diagrams package.

The AWS Documentation MCP server offers:

• search_documentation: Searches AWS documentation using the official AWS Documentation Search API.
• read_documentation: Fetches and converts AWS documentation pages into markdown.
• recommend: Provides content recommendations for AWS documentation pages.

Together, these tools help create accurate architecture diagrams adhering to AWS best practices.

Test Your Setup

To verify your setup, generate a simple diagram:

1. Start the Amazon Q CLI chat interface:

   q chat

2. Enter the prompt:

   Please create a diagram showing an EC2 instance in a VPC connecting to an external S3 bucket. Include essential networking components (VPC, subnets, Internet Gateway, Route Table) and security elements (Security Groups, NACLs), and clearly mark the connection between EC2 and S3. Label everything appropriately and indicate that all resources are in the us-east-1 region. Check for AWS documentation to ensure adherence to AWS best practices before creating the diagram.

Amazon Q CLI will generate and display a simple diagram based on your description. If you see the diagram, your environment is set up correctly.

Configuration Options

The AWS Diagram MCP server supports several configuration options to customize your diagramming experience:

• Output Directory: Diagrams are saved in a default directory, but you can specify a different location.
• Diagram Format: The default output format is PNG, but you can request SVG or other formats.
• Styling Options: Customize colors, shapes, and other stylistic elements in your prompts.

Now that your environment is set up, let’s dive into creating AWS architecture diagrams.

Create AWS Architecture Diagrams

This section walks through multiple AWS architecture diagrams using Amazon Q CLI with the AWS Diagram MCP server and AWS Documentation MCP server to ensure adherence to best practices. When you input a prompt, the system executes the following steps:

1. Interpret Requirements: Understands what you need.
2. Check Documentation: Validates against AWS best practices.
3. Generate Python Code: Creates the necessary code using the diagrams package.
4. Execute Code: Runs the code to produce the diagram.
5. Return Diagram: Outputs the final diagram as an image.

Example 1: Create a Web Application Architecture

To create a diagram for a web application hosted on AWS, enter:

Create a diagram for a simple web application with an Application Load Balancer, two EC2 instances, and an RDS database. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

The generated diagram will include key components necessary for the application architecture.

Example 2: Create a Multi-Tier Architecture

For a multi-tier architecture, use the prompt:

Create a diagram for a three-tier web application with a presentation tier (ALB and CloudFront), application tier (ECS with Fargate), and data tier (Aurora PostgreSQL). Include VPC with public and private subnets across multiple AZs. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

This will illustrate a robust architecture ensuring scalability and security.

Example 3: Create a Serverless Architecture

Prompt the system with:

Create a diagram for a serverless web application using API Gateway, Lambda, DynamoDB, and S3 for static website hosting. Include Cognito for user authentication and CloudFront for content delivery. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

The generated diagram will showcase a modern serverless application architecture.

Example 4: Create a Data Processing Diagram

To visualize a data processing pipeline, use:

Create a diagram for a data processing pipeline with components organized in clusters for data ingestion, processing, storage, and analytics. Include Kinesis, Lambda, S3, Glue, and QuickSight. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

This will demonstrate a complex data processing architecture.

Real-World Examples

E-Commerce Platform

For an e-commerce platform with a microservices architecture, prompt:

Create a diagram for an e-commerce platform with microservices architecture. Include components for product catalog, shopping cart, checkout, payment processing, order management, and user authentication. Ensure the architecture follows AWS best practices for scalability and security. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

Intelligent Document Processing Solution

To create a diagram for an IDP application on AWS:

Create a diagram for an intelligent document processing (IDP) application on AWS. Include components for document ingestion, OCR and text extraction, intelligent data extraction, human review, and data output/integration. Ensure the architecture follows AWS best practices for scalability and security. Check for AWS documentation related to intelligent document processing best practices to ensure it adheres to AWS best practices before you create the diagram.

Clean Up

If you no longer need the AWS Diagram MCP server, remove it from your configuration by editing the ~/.aws/amazonq/mcp.json file and commenting out or deleting the server entries.

Conclusion

In this post, we explored how to use the Amazon Q CLI with the AWS Documentation MCP and AWS Diagram MCP servers to create professional AWS architecture diagrams that follow AWS best practices. This approach offers significant advantages over traditional methods:

• Time Savings: Complex diagrams can be generated in minutes.
• Consistency: Maintain uniform style and conventions.
• Best Practices: Automatically incorporate AWS architectural guidelines.
• Iterative Refinement: Modify diagrams quickly via simple prompts.
• Validation: Ensure architectures align with official guidelines.

We encourage you to deepen your knowledge of the Model Context Protocol (MCP) and explore additional resources like the AWS Architecture Center and AWS Icons page for inspiration and best practices.

About the Authors

Joel Asante, an Austin-based Solutions Architect at AWS, specializes in secure and scalable cloud architectures for GovTech customers. He holds 13 AWS certifications and enjoys family time and sports.

Dunieski Otano, a Solutions Architect at AWS from Miami, focuses on Security, Machine Learning, and Serverless solutions, boasting 14 AWS certifications.

Varun Jasti, also a Solutions Architect at AWS, teaches compliance standards for AI solutions in the public sector and is passionate about tennis and swimming.

By mastering these tools, you can enhance your architecture diagramming processes, making them more effective and efficient. Happy diagramming!