DEV Community

Cover image for From Prompt to Diagram: AWS Architecture with Amazon Q CLI and MCP
AWS Community Builders profile image Sarvar Nadaf
Sarvar Nadaf for AWS Community Builders

Posted on • Edited on

From Prompt to Diagram: AWS Architecture with Amazon Q CLI and MCP

#aws #ai #genai #beginners

Important: This tutorial is performed on an EC2 instance running Ubuntu 22.04 LTS due to compatibility and reliability reasons.

👋 Hey there, tech enthusiasts!

I'm Sarvar, a Cloud Architect with a passion for transforming complex technological challenges into elegant solutions. With extensive experience spanning Cloud Operations (AWS & Azure), Data Operations, Analytics, DevOps, and Generative AI, I've had the privilege of architecting solutions for global enterprises that drive real business impact. Through this article series, I'm excited to share practical insights, best practices, and hands-on experiences from my journey in the tech world. Whether you're a seasoned professional or just starting out, I aim to break down complex concepts into digestible pieces that you can apply in your projects.

Let's dive in and explore the fascinating world of cloud technology together! 🚀

As cloud-native development continues to evolve, tools that enhance developer productivity directly from the command line have become essential. Amazon Q for Command Line (Amazon Q CLI) is one such tool, bringing the power of generative AI to the terminal. It enables developers to ask technical questions, generate scripts, troubleshoot issues, and even draw AWS architecture diagrams all without switching contexts or opening a browser. In this guide, we focus on configuring Amazon Q CLI on an Ubuntu 22.04 LTS (In my case I'm using EC2 instance), a reliable and widely used operating system for cloud environments. The setup also includes integrating the MCP (Model Context Protocol) server, which allows Amazon Q CLI to render real-time architecture diagrams based on plain English prompts.

So we will begin by installing the CLI, authenticating using a Builder ID, and then proceed to set up the Python environment, install necessary dependencies like Graphviz, and configure the MCP server. By the end of this article, you’ll have a fully functional local environment where you can interact with Amazon Q from the terminal and generate professional-grade AWS architecture diagrams with just a few commands.

Prerequisites

Before starting, ensure the following:

  1. Ubuntu 22.04 LTS OS
  2. Internet access from the instance
  3. A valid Builder ID or IAM Identity Center credentials
  4. Permission to run commands with sudo
  5. Ubuntu default user (do not use the root user)

Why Ubuntu 22.04 LTS is Ideal for Amazon Q CLI

Ubuntu 22.04 LTS is the most reliable OS for running Amazon Q CLI, offering stability, compatibility, and secure communication with AWS services. It includes all required dependencies like Python and OpenSSL, ensuring smooth installation and performance. The terminal environment supports real-time features such as code suggestions and command completion. I’ve personally tested Amazon Q CLI on Ubuntu 24.04 and other versions, but only 22.04 provided consistent and error-free functionality. Its long-term support and regular updates make it ideal for AWS development workflows.

Configure Amazon Q CLI

This section covers the step-by-step configuration of Amazon Q CLI on an Ubuntu 22.04 LTS instance to ensure seamless integration and optimal performance.

Step 1: Update System Packages

It’s always good practice to update your package list before installing new software.

sudo apt update -y
Enter fullscreen mode Exit fullscreen mode

Step 2: Download the Amazon Q CLI Package

Use wget to download the latest .deb package from the official Amazon Q release server:

wget https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb
Enter fullscreen mode Exit fullscreen mode

Step 3: Install Dependencies (Optional)

Before installing the package, make sure all required dependencies are present and if you have already perform 1st update command then this step is option for you you can skip it for now.

sudo apt-get install -f
Enter fullscreen mode Exit fullscreen mode

Step 4: Install the Amazon Q CLI Package

Now install the .deb package using dpkg:

sudo dpkg -i amazon-q.deb
Enter fullscreen mode Exit fullscreen mode

Step 5: Verify Amazon Q 

q --version
Enter fullscreen mode Exit fullscreen mode

If you face any dependency issues, re-run sudo apt-get install -f to auto-fix them.

Amazon Q CLI Login with Builder ID

After successfully installing Amazon Q CLI, the next step is to authenticate. Here's how to log in using your Builder ID:

Step 1: Run the Login Command

In your terminal, enter:

q login
Enter fullscreen mode Exit fullscreen mode

You’ll see a prompt with two options. Choose:

Use for Free with Builder ID
Enter fullscreen mode Exit fullscreen mode

If you don’t have a Builder ID yet, you can create one using your email during this step.

Step 2: Confirm Authorization in Browser

Amazon Q will generate a unique confirmation link and code. You must:

  • Manually open the provided link in a browser and login with your mail id.

  • Enter the verification code when prompted.

Step 3: Allow Access

Once the code is verified, Amazon Q will ask for permission to access your Builder ID account. Click Allow.

Launch Amazon Q CLI

Start Amazon Q using the following command:

q
Enter fullscreen mode Exit fullscreen mode

Configure MCP Server for Architecture Diagrams

This section covers how to set up an MCP (Model Context Protocol) server that allows Amazon Q to generate AWS architecture diagrams through structured prompts.

Step 1: Install Python 3.10

To run the MCP server locally, Amazon Q requires Python 3.10. Here's a breakdown of each command to install it properly on Ubuntu 22.04 LTS.

1. Update the package list

sudo apt update -y
Enter fullscreen mode Exit fullscreen mode

What it does:
Fetches the latest list of available packages and versions from the Ubuntu repositories. Always a good first step before installing anything new.

2. Install software-properties-common

sudo apt install -y software-properties-common
Enter fullscreen mode Exit fullscreen mode

What it does:
Installs a package that allows you to manage additional repositories (like PPAs). Required to add the Deadsnakes PPA for Python 3.10.

3. Add the Deadsnakes PPA

sudo add-apt-repository ppa:deadsnakes/ppa -y
Enter fullscreen mode Exit fullscreen mode

What it does:
Adds the Deadsnakes Personal Package Archive (PPA) to your system. This PPA maintains up-to-date versions of Python not available in the default Ubuntu repos.

4. Install Python 3.10 and related tools

sudo apt install -y python3.10 python3.10-venv python3.10-dev
Enter fullscreen mode Exit fullscreen mode

What it does:

  • python3.10: Installs the Python 3.10 interpreter
  • python3.10-venv: Enables creating virtual environments with python3.10 -m venv
  • python3.10-dev: Provides headers and development tools needed to build Python packages with native extensions

Once these steps are complete, Python 3.10 will be available on your EC2 instance.

You can verify the version using:

python3.10 --version
Enter fullscreen mode Exit fullscreen mode

Step 2: Set Up a Virtual Environment

Create a virtual environment to isolate the MCP server:

python3.10 -m venv ~/aws-diagram-mcp-env
source ~/aws-diagram-mcp-env/bin/activate
Enter fullscreen mode Exit fullscreen mode

Step 3: Install MCP Server and Dependencies

Use pip to install the required libraries:

pip install --upgrade pip
pip install uv uvenv awslabs.aws-diagram-mcp-server trio
Enter fullscreen mode Exit fullscreen mode

Step 4: Configure Amazon Q to Use the MCP Server

First, change directory to the Amazon Q configuration directory:

mkdir -p ~/.aws/amazonq
Enter fullscreen mode Exit fullscreen mode

Then create the config file at ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

You can create the file using nano or vim:

nano ~/aws/amazonq/mcp.json
Enter fullscreen mode Exit fullscreen mode

Paste the above configuration and save the file.

Install Graphviz for Diagram Rendering

The MCP server used by Amazon Q CLI often relies on Graphviz to generate architecture diagrams in formats like SVG or PNG. If it's not already installed on your system, you may encounter rendering or export errors when generating visual outputs.

Install it using the following command:

sudo apt update && sudo apt install -y graphviz
Enter fullscreen mode Exit fullscreen mode

Once installed, Amazon Q CLI can generate and visualize AWS architecture diagrams more reliably via the MCP server.

Optional: Use Amazon Q CLI to Set Up MCP

Alternatively, Amazon Q CLI itself can help you set up the MCP server if you provide the right prompts. You can ask:

Set up a local MCP server for AWS architecture diagram generation
Enter fullscreen mode Exit fullscreen mode

This approach may simplify the process by handling package installation and configuration automatically.

Next Step

After successfully completing the setup, initiate Amazon Q CLI by executing the q command. This will trigger the initialization of the MCP server, as illustrated in the image below.

Let's Generate Real-Time Architecture Diagrams

Once your MCP server is configured and Amazon Q CLI is running, you can ask Amazon Q to generate architectural diagrams for various AWS use cases. These diagrams will be saved as image files (typically PNG or SVG) under:

~/.aws/amazonq/generated-diagrams/
Enter fullscreen mode Exit fullscreen mode

Example Prompt 1: Serverless Web Application 

Draw an architecture diagram for a serverless web app using AWS Lambda, API Gateway, and DynamoDB
Enter fullscreen mode Exit fullscreen mode

What it shows:

  • Client/browser requests via API Gateway
  • Backend logic through AWS Lambda
  • Persistent storage using DynamoDB

Example Prompt 2: Multi-AZ Highly Available Web App 

Draw an AWS architecture diagram for a high availability web application using Application Load Balancer, EC2 in Auto Scaling Group across two Availability Zones, and an RDS database
Enter fullscreen mode Exit fullscreen mode

What it shows:

  • ALB routing traffic to EC2 instances
  • Auto Scaling Group distributing across AZs
  • RDS deployed in Multi-AZ mode for resilience

Example Prompt 3: Data Lake on S3 with Glue and Athena 

Generate an architecture diagram for a data lake on AWS using S3, AWS Glue for cataloging and ETL, and Amazon Athena for querying
Enter fullscreen mode Exit fullscreen mode

What it shows:

  • S3 as raw, processed, and curated zones
  • AWS Glue jobs and Data Catalog
  • Athena for serverless querying

Example Prompt 4: Event-Driven Microservices with SNS and SQS 

Create an AWS architecture diagram for event-driven microservices using Amazon SNS to publish events and SQS for decoupled processing
Enter fullscreen mode Exit fullscreen mode

What it shows:

  • SNS topic publishing messages
  • SQS queues receiving events
  • Lambda or ECS services processing events asynchronously

Example Prompt 5: CI/CD Pipeline using CodePipeline and CodeDeploy 

Draw an AWS architecture diagram for a CI/CD pipeline using CodeCommit, CodeBuild, CodePipeline, and CodeDeploy
Enter fullscreen mode Exit fullscreen mode

What it shows:

  • CodeCommit for source control
  • CodeBuild for builds and tests
  • CodePipeline for orchestration
  • CodeDeploy pushing code to EC2, ECS, or Lambda

Note: These prompts can be entered directly into the Amazon Q CLI once the MCP server is running. The CLI will respond with both a description and a downloadable image file (saved locally).

Conclusion: Amazon Q CLI brings the power of GenAI directly to your terminal, enabling efficient command-line development, real-time support, and architecture visualization. With its easy setup on an Ubuntu EC2 instance and optional MCP server integration, you can generate dynamic AWS diagrams on demand using plain English prompts. This setup not only boosts developer productivity but also simplifies architecture planning, making it an invaluable tool for cloud engineers and solution architects. Whether you're building serverless apps or planning highly available architectures, Amazon Q CLI combined with MCP offers an intelligent, interactive experience right from your shell. Stay tuned for more tutorials exploring advanced prompts, automation, and troubleshooting scenarios with Amazon Q.

📌 Wrapping Up
Thank you for investing your time in reading this article! I hope these insights have provided you with practical value and a clearer understanding of the topic. Your engagement and learning journey matter to me.

💡 What's Next?
Stay tuned for more in-depth articles where we'll explore other exciting aspects of cloud operations, GenAI, DevOps, and data operations. Follow me for weekly content that aims to demystify complex tech concepts and provide actionable insights.

🤝 Let's Connect!
I'd love to hear your thoughts and experiences! Drop your comments below or connect with me on LinkedIn. Your feedback helps me create more valuable content for our tech community.

Happy Learning! 🚀

Top comments (4)

Collapse
 
l_long_fa2bea20f6ad6820e profile image
Lê Long •

can i using github copilot mcp instead or just with amazon q

Collapse
 
sarvar_04 profile image
Sarvar Nadaf AWS Community Builders •

i think yes, you can use GitHub Copilot MCP as well, but in this article I focused on Amazon Q since it integrates directly with AWS services and workflows.

Some comments may only be visible to logged-in visitors. Sign in to view all comments.