Building AWS Architecture Diagrams Using Amazon Q CLI & MCP

Have you ever struggled to create cloud architecture diagrams for your AWS projects? Whether you’re planning a scalable app or just documenting your infrastructure, drawing diagrams manually can be… well, a pain.

Good news: With Amazon Q CLI and MCP servers, you can generate beautiful, detailed AWS diagrams just by typing what you want. That’s right, no more dragging and dropping icons for hours!

In this blog, I’ll walk you through how to set everything up, step-by-step and we’ll even try generating a diagram with a simple prompt.

What’s Amazon Q CLI (and MCP)?

Amazon Q CLI is a command-line tool powered by AI that lets you interact with your AWS resources, ask questions, and even generate architecture diagrams based on your prompts.

To make the diagram magic happen, we need to integrate MCP servers (Model Context Protocol). These servers take your prompt, understand what you’re trying to build, and return a nicely drawn diagram.

Let’s Get Started: Installing Amazon Q CLI

I’ll cover all three major platforms: Mac, Ubuntu (Linux), and Windows (WSL). For this guide, I’ll go with Windows WSL myself, but feel free to pick your platform.

MacOS Installation:

brew install amazon-q

Or download the installer

Ubuntu Installation:

sudo apt-get update
sudo apt install libfuse2

curl --proto '=https' --tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o amazon-q.deb
sudo apt install -y ./amazon-q.deb

Login to Amazon Q:

q login

You’ll need a Builder ID to authenticate.

Windows (WSL) Installation:

• Install WSL:
  Microsoft WSL Setup Guide
• Download & Install Amazon Q CLI:

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"

unzip q.zip

./q/install.sh

Add it to your PATH:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Launch Amazon Q:

q

You’ll be prompted to log in either via AWS Builder ID or IAM Identity Center (SSO). Once you’re in, you’re all set.

Enabling MCP Servers for Diagram Generation

Here’s where things get cool.

To create diagrams, Amazon Q needs to run a few background services called MCP servers. Let’s enable them.

Step 1: Install uv (tool to run MCP servers)

sudo snap install astral-uv --classic

Step 2: Configure MCP

Create the file mcp.json in the following path:

nano ~/.aws/amazonq/mcp.json

Paste this into the file:

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

Save and exit from nano editor, Now run q again:

q

Boom your Q CLI is now powered up and ready to draw!

Let’s Try It: Generate a Diagram with One Prompt

All you have to do is type a description. Here’s an example:

Create a fault-tolerant, highly available real-time GPS tracking system using AWS ECS Fargate, Redis (ElastiCache), Aurora Serverless, and API Gateway. Use ALB for socket routing, integrate CloudWatch for logging, and S3 for archival storage. CI/CD should be managed by CodePipeline.

Amazon Q understands your intent, activates the MCP server, and generates a clean PNG diagram within seconds.

Behind the Scenes: How It Works

Here’s what happens behind the scenes:

1. You give Amazon Q a prompt.
2. It recognizes it as a diagram request.
3. It launches the MCP server defined in mcp.json.
4. Your request is converted to Python code (using the diagrams library).
5. AWS services become nodes, connections become edges.
6. Graphviz renders the final PNG image.
7. Voila! Q returns the image path so you can open or share it.

Final Thoughts

Honestly, this tool blew my mind.

If you’re someone who builds on AWS and hates spending hours in Lucidchart or Draw.io, Amazon Q CLI with MCP is a game-changer. It takes your vision, interprets it, and hands you a polished diagram — all from the terminal.

Try it out. You’ll be amazed at what you can build with just a sentence.

Have Questions?

If you’re experimenting with Amazon Q CLI and MCP for infrastructure automation or architecture diagrams, I’d be happy to connect. Feel free to reach out with questions, implementation stories, or ideas for extending these tools.

Let’s continue building better, faster, and smarter infrastructure workflows.

Let’s #BuildOnAWS !

References:

GitHub Link: https://github.com/awslabs/mcp

AWS Diagram MCP Server: https://awslabs.github.io/mcp/servers/aws-diagram-mcp-server/