Construct AWS structure diagrams utilizing Amazon Q CLI and MCP

Creating skilled AWS structure diagrams is a basic job for options architects, builders, and technical groups. These diagrams function important communication instruments for stakeholders, documentation of compliance necessities, and blueprints for implementation groups. Nevertheless, 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 most recent AWS service icons and finest practices difficult.
• Troublesome upkeep – Updating diagrams as architectures evolve can change into more and more burdensome

Amazon Q Developer CLI with the Mannequin Context Protocol (MCP) affords a streamlined strategy to creating AWS structure diagrams. Through the use of generative AI by way of pure language prompts, architects can now generate skilled diagrams in minutes somewhat than hours, whereas adhering to AWS finest practices.

On this put up, we discover tips on how to use Amazon Q Developer CLI with the AWS Diagram MCP and the AWS Documentation MCP servers to create refined structure diagrams that observe AWS finest practices. We focus on methods for primary 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 way of pure language prompts, making it a useful instrument for numerous improvement duties.

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

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

• Host – A program or AI instrument that requires entry to knowledge by way of the MCP protocol, resembling Anthropic’s Claude Desktop, an built-in improvement surroundings (IDE), AWS MCP CLI, or different AI functions
• Consumer – Protocol purchasers that preserve one-to-one connections with server
• Server – Light-weight packages that expose capabilities by way of standardized MCP or act as instruments
• Information sources – Native knowledge sources resembling databases and file programs, or exterior programs accessible over the web by way of APIs (net APIs) that MCP servers can join with

As introduced in April 2025, MCP allows 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 allows Amazon Q to generate structure diagrams utilizing the Python diagrams package deal, with entry to the whole AWS icon set and architectural finest practices.

Stipulations

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

Arrange your surroundings

Earlier than you can begin creating diagrams, it is advisable 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 accessible 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 is 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 routinely 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 accessible icons from the diagrams package deal, organized by supplier and repair class
• get_diagram_examples – Supplies instance code for various kinds of diagrams (AWS, sequence, movement, class, and others)
• generate_diagram – Creates a diagram from Python code utilizing the diagrams package deal

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 can assist you create correct structure diagrams that observe AWS finest practices.

Take a look at your setup

Let’s confirm that all the pieces is working accurately 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 exhibiting an EC2 occasion in a VPC connecting to an exterior S3 bucket. Embody important networking elements (VPC, subnets, Web Gateway, Route Desk), safety parts (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. Verify for AWS documentation to make sure it adheres to AWS finest 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 exhibiting the requested structure. Your diagram ought to look just like the next screenshot, although there may be variations in format, styling, or particular particulars as a result of it’s created utilizing generative AI. The core architectural elements and relationships will probably be represented, however the precise visible presentation would possibly differ barely with every technology.
   
   When you see the diagram, your surroundings is ready up accurately. When you 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 may specify a special location in your prompts.
• Diagram format – The default output format is PNG, however you possibly can request different codecs like SVG in your prompts.
• Styling choices – You may specify colours, shapes, and different styling parts in your prompts.

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

Create AWS structure diagrams

On this part, we stroll by way of 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 verify our necessities observe finest practices.

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

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

This course of occurs seamlessly, so you possibly can deal with describing what you need somewhat than tips on how to create it.

AWS structure diagrams usually embrace the next elements:

• Nodes – AWS providers and assets
• Edges – Connections between nodes exhibiting relationships or knowledge movement
• Clusters – Logical groupings of nodes, resembling 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 net utility hosted on AWS. Enter the next immediate:

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

The generated diagram exhibits the next key elements:

Instance 2: Create a multi-tier structure

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

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

The diagram exhibits the next key elements:

• A presentation tier in public subnets
• An utility tier in non-public subnets
• A knowledge tier in remoted non-public subnets
• Correct safety group configurations
• Visitors movement 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 net utility utilizing API Gateway, Lambda, DynamoDB, and S3 for static web site internet hosting. Embody Cognito for consumer authentication and CloudFront for content material supply. Verify for AWS documentation to make sure it adheres to AWS finest practices earlier than you create the diagram.

The diagram consists of the next key elements:

Instance 4: Create an information processing diagram

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

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

The diagram organizes elements into distinct clusters:

Actual-world examples

Let’s discover some real-world structure patterns and tips on how 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 preserve excessive availability. We use the next immediate to create an instance diagram:

Create a diagram for an e-commerce platform with microservices structure. Embody elements for product catalog, buying cart, checkout, fee processing, order administration, and consumer authentication. Make sure the structure follows AWS finest practices for scalability and safety. Verify for AWS documentation to make sure it adheres to AWS finest practices earlier than you create the diagram.

The diagram consists of the next key elements:

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. Embody elements for doc ingestion, OCR and textual content extraction, clever knowledge extraction (utilizing NLP and/or laptop imaginative and prescient), human evaluation and validation, and knowledge output/integration. Make sure the structure follows AWS finest practices for scalability and safety, leveraging providers like S3, Lambda, Textract, Comprehend, SageMaker (for customized fashions, if relevant), and doubtlessly Augmented AI (A2I). Verify for AWS documentation associated to clever doc processing finest practices to make sure it adheres to AWS finest practices earlier than you create the diagram.

The diagram consists of the next key elements:

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

Clear up

When you not want to make use of the AWS Value Evaluation MCP server with Amazon Q CLI, you possibly can 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 once you begin Amazon Q CLI sooner or later.

Conclusion

On this put up, we explored tips on how 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 finest practices referenced from official AWS documentation. This strategy affords important benefits over conventional diagramming strategies:

• Time financial savings – Generate complicated diagrams in minutes as an alternative of hours
• Consistency – Be sure that diagrams observe the identical type and conventions
• Finest practices – Mechanically incorporate AWS architectural tips
• Iterative refinement – Shortly modify diagrams by way of easy prompts
• Validation – Verify 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 in regards to the Mannequin Context Protocol (MCP) to know the way it enhances the capabilities of Amazon Q. When looking for inspiration to your personal designs, the AWS Structure Middle affords a wealth of reference architectures that observe finest practices. For creating visually constant diagrams, be sure you go to the AWS Icons web page, the place you could find the whole official icon set. And to remain on the innovative of those instruments, regulate updates to the official AWS MCP Servers—they’re continually evolving with new options to make your diagramming expertise even higher.

Concerning the Authors

Joel Asante, an Austin-based Options Architect at Amazon Net Providers (AWS), works with GovTech (Authorities Expertise) prospects. With a robust background in knowledge science and utility improvement, he brings deep technical experience to creating safe and scalable cloud architectures for his prospects. Joel is obsessed with knowledge analytics, machine studying, and robotics, leveraging his improvement expertise to design progressive options that meet complicated 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 Net Providers primarily based 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 accessible, scalable, and safe options. Dunieski holds 14 AWS certifications and is an AWS Golden Jacket recipient. In his free time, you will see him spending time along with his household and canine, watching an awesome film, coding, or flying his drone.

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