Construct AWS structure diagrams utilizing Amazon Q CLI and MCP

Creating skilled AWS structure diagrams is a elementary activity for options architects, builders, and technical groups. These diagrams function important communication instruments for stakeholders, documentation of compliance necessities, and blueprints for implementation groups. Nonetheless, conventional diagramming approaches current a number of challenges:

• Time-consuming course of – Creating detailed structure diagrams manually can take hours and even days
• Steep studying curve – Studying specialised diagramming instruments requires important funding
• Inconsistent styling – Sustaining visible consistency throughout a number of diagrams is tough
• Outdated AWS icons – Maintaining with the newest AWS service icons and greatest practices difficult.
• Tough upkeep – Updating diagrams as architectures evolve can turn out to be more and more burdensome

Amazon Q Developer CLI with the Model Context Protocol (MCP) provides a streamlined method to creating AWS structure diagrams. Through the use of generative AI by pure language prompts, architects can now generate skilled diagrams in minutes reasonably than hours, whereas adhering to AWS greatest practices.

On this put up, we discover the way to use Amazon Q Developer CLI with the AWS Diagram MCP and the AWS Documentation MCP servers to create subtle structure diagrams that comply with AWS greatest practices. We focus on strategies for fundamental diagrams and real-world diagrams, with detailed examples and step-by-step directions.

Resolution overview

Amazon Q Developer CLI is a command line interface that brings the generative AI capabilities of Amazon Q on to your terminal. Builders can work together with Amazon Q by pure language prompts, making it a useful instrument for numerous improvement duties.

Developed by Anthropic as an open protocol, the Model Context Protocol (MCP) gives a standardized strategy to join AI fashions to just about any information supply or instrument. Utilizing a client-server architecture (as illustrated within the following diagram), the MCP helps builders expose their information by light-weight MCP servers whereas constructing AI purposes as MCP purchasers that join to those servers.

The MCP makes use of a client-server structure containing the next parts:

• Host – A program or AI instrument that requires entry to information by the MCP protocol, similar to Anthropic’s Claude Desktop, an built-in improvement surroundings (IDE), AWS MCP CLI, or different AI purposes
• Shopper – Protocol purchasers that keep one-to-one connections with server
• Server – Light-weight applications that expose capabilities by standardized MCP or act as instruments
• Knowledge sources – Native information sources similar to databases and file methods, or exterior methods obtainable over the web by APIs (internet APIs) that MCP servers can join with

As announced in April 2025, MCP permits Amazon Q Developer to attach with specialised servers that reach its capabilities past what’s attainable with the bottom mannequin alone. MCP servers act as plugins for Amazon Q, offering domain-specific data and performance. The AWS Diagram MCP server particularly permits Amazon Q to generate structure diagrams utilizing the Python diagrams bundle, with entry to the entire AWS icon set and architectural greatest practices.

Stipulations

To implement this answer, you will need to have an AWS account with acceptable permissions and comply with the steps beneath.

Arrange your surroundings

Earlier than you can begin creating diagrams, you’ll want to arrange your surroundings with Amazon Q CLI, the AWS Diagram MCP server, and AWS Documentation MCP server. This part gives detailed directions for set up and configuration.

Set up Amazon Q Developer CLI

Amazon Q Developer CLI is obtainable as a standalone set up. Full the next steps to put in it:

1. Obtain and set up Amazon Q Developer CLI. For directions, see Utilizing Amazon Q Developer on the command line.
2. Confirm the set up by working the next command: q --version
   It’s best to see output just like the next: Amazon Q Developer CLI model 1.x.x
3. Configure Amazon Q CLI along with your AWS credentials: q login
4. Select the login technique appropriate for you:

Arrange MCP servers

Full the next steps to arrange your MCP servers:

1. Set up uv utilizing the next command: pip set up uv
2. Set up Python 3.10 or newer: uv python set up 3.10
3. Set up GraphViz to your working system.
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
    }
  }
}

Now, Amazon Q CLI mechanically discovers MCP servers within the ~/.aws/amazonq/mcp.json file.

Understanding MCP server instruments

The AWS Diagram MCP server gives a number of highly effective instruments:

• list_icons – Lists obtainable icons from the diagrams bundle, organized by supplier and repair class
• get_diagram_examples – Gives instance code for several types of diagrams (AWS, sequence, circulation, class, and others)
• generate_diagram – Creates a diagram from Python code utilizing the diagrams bundle

The AWS Documentation MCP server gives the next helpful instruments:

• search_documentation – Searches AWS documentation utilizing the official AWS Documentation Search API
• read_documentation – Fetches and converts AWS documentation pages to markdown format
• advocate – Will get content material suggestions for AWS documentation pages

These instruments work collectively that will help you create correct structure diagrams that comply with AWS greatest practices.

Take a look at your setup

Let’s confirm that all the pieces is working appropriately by producing a easy diagram:

1. Begin the Amazon Q CLI chat interface and confirm the output exhibits the MCP servers being loaded and initialized: q chat
   
2. Within the chat interface, enter the next immediate:
   Please create a diagram displaying an EC2 occasion in a VPC connecting to an exterior S3 bucket. Embrace important networking parts (VPC, subnets, Web Gateway, Route Desk), safety components (Safety Teams, NACLs), and clearly mark the connection between EC2 and S3. Label all the pieces appropriately concisely and point out that every one assets are within the us-east-1 area. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram.
3. Amazon Q CLI will ask you to belief the instrument that’s getting used; enter t to belief it.Amazon Q CLI will generate and show a easy diagram displaying the requested structure. Your diagram ought to look just like the next screenshot, although there may be variations in structure, styling, or particular particulars as a result of it’s created utilizing generative AI. The core architectural parts and relationships will probably be represented, however the precise visible presentation may differ barely with every era.
   
   If you happen to see the diagram, your surroundings is about up appropriately. If you happen to encounter points, confirm that Amazon Q CLI can entry the MCP servers by ensuring you put in the mandatory instruments and the servers are within the ~/.aws/amazonq/mcp.json file.

Configuration choices

The AWS Diagram MCP server helps a number of configuration choices to customise your diagramming expertise:

• Output listing – By default, diagrams are saved in a generated-diagrams listing in your present working listing. You’ll be able to specify a distinct location in your prompts.
• Diagram format – The default output format is PNG, however you may request different codecs like SVG in your prompts.
• Styling choices – You’ll be able to specify colours, shapes, and different styling components in your prompts.

Now that the environment is about up, let’s create extra diagrams.

Create AWS structure diagrams

On this part, we stroll by the method of a number of AWS structure diagrams utilizing Amazon Q CLI with the AWS Diagram MCP server and AWS Documentation MCP server to ensure our necessities comply with greatest practices.

Once you present a immediate to Amazon Q CLI, the AWS Diagram and Documentation MCP servers full the next steps:

1. Interpret your necessities.
2. Test for greatest practices on the AWS documentation.
3. Generate Python code utilizing the diagrams bundle.
4. Execute the code to create the diagram.
5. Return the diagram as a picture.

This course of occurs seamlessly, so you may deal with describing what you need reasonably than the way to create it.

AWS structure diagrams sometimes embrace the next parts:

• Nodes – AWS providers and assets
• Edges – Connections between nodes displaying relationships or information circulation
• Clusters – Logical groupings of nodes, similar to digital non-public clouds (VPCs), subnets, and Availability Zones
• Labels – Textual content descriptions for nodes and connections

Instance 1: Create an internet utility structure

Let’s create a diagram for a easy internet utility hosted on AWS. Enter the next immediate:

Create a diagram for a easy internet utility with an Software Load Balancer, two EC2 cases, and an RDS database. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram

The generated diagram exhibits the next key parts:

Instance 2: Create a multi-tier structure

Multi-tier architectures separate purposes into useful layers (presentation, utility, and information) to enhance scalability and safety. We use the next immediate to create our diagram:

Create a diagram for a three-tier internet utility with a presentation tier (ALB and CloudFront), utility tier (ECS with Fargate), and information tier (Aurora PostgreSQL). Embrace VPC with private and non-private subnets throughout a number of AZs. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram.

The diagram exhibits the next key parts:

• A presentation tier in public subnets
• An utility tier in non-public subnets
• An information tier in remoted non-public subnets
• Correct safety group configurations
• Visitors circulation between tiers

Instance 3: Create a serverless structure

We use the next immediate to create a diagram for a serverless structure:

Create a diagram for a serverless internet utility utilizing API Gateway, Lambda, DynamoDB, and S3 for static web site internet hosting. Embrace Cognito for consumer authentication and CloudFront for content material supply. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram.

The diagram consists of the next key parts:

Instance 4: Create a knowledge processing diagram

We use the next immediate to create a diagram for a knowledge processing pipeline:

Create a diagram for a knowledge processing pipeline with parts organized in clusters for information ingestion, processing, storage, and analytics. Embrace Kinesis, Lambda, S3, Glue, and QuickSight. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram.

The diagram organizes parts into distinct clusters:

Actual-world examples

Let’s discover some real-world structure patterns and the way to create diagrams for them utilizing Amazon Q CLI with the AWS Diagram MCP server.

Ecommerce platform

Ecommerce platforms require scalable, resilient architectures to deal with variable site visitors and keep excessive availability. We use the next immediate to create an instance diagram:

Create a diagram for an e-commerce platform with microservices structure. Embrace parts for product catalog, procuring cart, checkout, cost processing, order administration, and consumer authentication. Make sure the structure follows AWS greatest practices for scalability and safety. Test for AWS documentation to make sure it adheres to AWS greatest practices earlier than you create the diagram.

The diagram consists of the next key parts:

Clever doc processing answer

We use the next immediate to create a diagram for an clever doc processing (IDP) structure:

Create a diagram for an clever doc processing (IDP) utility on AWS. Embrace parts for doc ingestion, OCR and textual content extraction, clever information extraction (utilizing NLP and/or laptop imaginative and prescient), human assessment and validation, and information output/integration. Make sure the structure follows AWS greatest practices for scalability and safety, leveraging providers like S3, Lambda, Textract, Comprehend, SageMaker (for customized fashions, if relevant), and probably Augmented AI (A2I). Test for AWS documentation associated to clever doc processing greatest practices to make sure it adheres to AWS greatest practices earlier than you create the diagram.

The diagram consists of the next key parts:

• Amazon API Gateway because the entry level for shopper purposes, offering a safe and scalable interface
• Microservices applied as containers in ECS with Fargate, enabling versatile and scalable processing
• Amazon RDS databases for product catalog, procuring cart, and order information, offering dependable structured information storage
• Amazon ElastiCache for product information caching and session administration, bettering efficiency and consumer expertise
• Amazon Cognito for authentication, guaranteeing safe entry management
• Amazon Simple Queue Service and Amazon Simple Notification Service for asynchronous communication between providers, enabling decoupled and resilient structure
• Amazon CloudFront for content material supply and static property from S3, optimizing international efficiency
• Amazon Route53 for DNS administration, offering dependable routing
• AWS WAF for internet utility safety, defending towards widespread internet exploits
• AWS Lambda features for serverless microservice implementation, providing cost-effective scaling
• AWS Secrets Manager for safe credential storage, enhancing safety posture
• Amazon CloudWatch for monitoring and observability, offering insights into system efficiency and well being.

Clear up

If you happen to not want to make use of the AWS Price Evaluation MCP server with Amazon Q CLI, you may take away it out of your configuration:

1. Open your ~/.aws/amazonq/mcp.json file.
2. Take away or remark out the MCP server entries.
3. Save the file.

It will forestall the server from being loaded if you begin Amazon Q CLI sooner or later.

Conclusion

On this put up, we explored the way to use Amazon Q CLI with the AWS Documentation MCP and AWS Diagram MCP servers to create skilled AWS structure diagrams that adhere to AWS greatest practices referenced from official AWS documentation. This method provides important benefits over conventional diagramming strategies:

• Time financial savings – Generate advanced diagrams in minutes as a substitute of hours
• Consistency – Ensure that diagrams comply with the identical type and conventions
• Greatest practices – Routinely incorporate AWS architectural tips
• Iterative refinement – Shortly modify diagrams by easy prompts
• Validation – Test architectures towards official AWS documentation and proposals

As you proceed your journey with AWS structure diagrams, we encourage you to deepen your data by studying extra concerning the Model Context Protocol (MCP) to know the way it enhances the capabilities of Amazon Q. When looking for inspiration to your personal designs, the AWS Architecture Center provides a wealth of reference architectures that comply with greatest practices. For creating visually constant diagrams, you should definitely go to the AWS Icons page, the place you will discover the entire official icon set. And to remain on the innovative of those instruments, control updates to the official AWS MCP Servers—they’re continuously evolving with new options to make your diagramming expertise even higher.

Concerning the Authors

Joel Asante, an Austin-based Options Architect at Amazon Internet Providers (AWS), works with GovTech (Authorities Expertise) prospects. With a powerful background in information science and utility improvement, he brings deep technical experience to creating safe and scalable cloud architectures for his prospects. Joel is enthusiastic about information analytics, machine studying, and robotics, leveraging his improvement expertise to design progressive options that meet advanced authorities necessities. He holds 13 AWS certifications and enjoys household time, health, and cheering for the Kansas Metropolis Chiefs and Los Angeles Lakers in his spare time.

Dunieski Otano is a Options Architect at Amazon Internet Providers based mostly out of Miami, Florida. He works with World Broad Public Sector MNO (Multi-Worldwide Organizations) prospects. His ardour is Safety, Machine Studying and Synthetic Intelligence, and Serverless. He works along with his prospects to assist them construct and deploy excessive obtainable, scalable, and safe options. Dunieski holds 14 AWS certifications and is an AWS Golden Jacket recipient. In his free time, you will discover him spending time along with his household and canine, watching an important film, coding, or flying his drone.

Varun Jasti is a Options Architect at Amazon Internet Providers, working with AWS Companions to design and scale synthetic intelligence options for public sector use instances to satisfy compliance requirements. With a background in Pc Science, his work covers broad vary of ML use instances primarily specializing in LLM coaching/inferencing and laptop imaginative and prescient. In his spare time, he loves taking part in tennis and swimming.