All Posts
·8 min read·

Create AWS Architecture Diagrams with Amazon Q + MCP

Use Amazon Q Developer + MCP to generate professional AWS architecture diagrams through natural language prompts.

AWS QMCPArchitectureAI

AWS Q CLI with Diagram MCP Server

Architecture for Generating AWS Diagrams

UserPrompt
Prompt
▼
AWS QCLI
MCP
▼
Diagram MCPServer
Render
▼
OutputPNG/SVG

What is Amazon Q Developer?

Amazon Q Developer is AWS's AI-powered coding assistant that lives inside your IDE and terminal. Unlike generic AI chatbots, Q has deep understanding of AWS services, architecture patterns, and best practices.

In the IDE

  • ▹Code generation & completion for AWS SDKs
  • ▹Inline chat for debugging & refactoring
  • ▹Security vulnerability scanning
  • ▹Code transformation (Java upgrades, .NET porting)

In the CLI

  • ▹Natural language to shell commands
  • ▹Agentic mode with tool use (MCP support)
  • ▹Context-aware — reads your project files
  • ▹Executes tasks: create files, run commands, manage infra

Key point: Amazon Q Developer CLI supports MCP natively — meaning it can connect to external tools and APIs through the Model Context Protocol, making it a powerful DevOps agent.

What is Model Context Protocol (MCP)?

MCP is an open standard (created by Anthropic) that defines how AI applications communicate with external tools. Think of it as a universal adapter — once a tool has an MCP server, any AI that speaks MCP can use it.

┌──────────────┐         ┌───────────────┐         ┌──────────────┐
│   AI Host    │  JSON   │  MCP Server   │   SDK   │  External    │
│  (Amazon Q)  │◄──────►│  (Tool Layer) │◄───────►│  Service     │
│              │   RPC   │               │         │  (AWS, Git…) │
└──────────────┘         └───────────────┘         └──────────────┘

Tools

Functions the AI can call — like "create diagram", "list EC2 instances", or "deploy stack".

Resources

Data the AI can read — like docs, configs, or current infrastructure state.

Prompts

Pre-built templates for common workflows the AI can use.

Install Amazon Q Developer CLI

Ubuntu / Linux (Headless Server)

# Download the CLI-only zip (no GUI dependencies needed)

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

# Unzip and install

unzip q-cli.zip sudo mv q /usr/local/bin/q

# Verify & login

q --version q login

Note: The .deb package (amazon-q.deb) is for desktop Linux with GUI. On headless servers (like EC2), use the CLI zip above to avoid GTK/WebKit dependency issues.

Ubuntu / Linux (Desktop with GUI)

# Download the .deb package

curl "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/amazon-q.deb" -o amazon-q.deb

# Install with dependencies

sudo apt-get update sudo dpkg -i amazon-q.deb sudo apt-get install -f -y

# Verify & login

q --version q login

macOS

# Using Homebrew

brew install --cask amazon-q

# Or download from AWS website

# https://aws.amazon.com/q/developer/

# Login

q login

Note: You need an AWS Builder ID (free) or IAM Identity Center credentials. The free tier includes full Q Developer CLI access with MCP support.

MCP Server Setup — AWS Architecture Diagrams

We'll configure the awslabs.aws-diagram-mcp-server to let Amazon Q generate architecture diagrams from plain English.

1

Install uv & uvx

curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version uvx --help
2

Configure MCP

Create ~/.aws/amazonq/mcp.json

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

Verify Connection

# Start Q chat

q chat

# Ask Q

> What MCP tools do you have available?

Q should list the diagram tool among its available MCP tools.

4

Generate Your First Diagram

You:

"Create an architecture diagram for a 3-tier web app on AWS with ALB, ECS Fargate, and Aurora PostgreSQL in a VPC with public and private subnets."

Amazon Q (via MCP):

I'll create that architecture diagram using the AWS diagram tool.

Calling tool: create_diagram
├── title: "3-Tier Web Application on AWS"
├── services:
│   ├── Route 53 (DNS)
│   ├── ALB (Public Subnet)
│   ├── ECS Fargate (Private Subnet)
│   ├── Aurora PostgreSQL (Private Subnet)
│   └── NAT Gateway
├── connections:
│   ├── Route53 → ALB
│   ├── ALB → ECS Fargate
│   ├── ECS Fargate → Aurora
│   └── ECS Fargate → NAT Gateway → Internet
└── output: ./aws-architecture.png

Done! Diagram saved to ./aws-architecture.png

More Prompt Examples

Serverless

"Draw a serverless architecture with API Gateway, Lambda, DynamoDB, and S3 with CloudFront."

Microservices on EKS

"Create a diagram for microservices on EKS with App Mesh, ECR, CodePipeline, and CloudWatch."

Data Pipeline

"Generate an architecture diagram for a real-time data pipeline: Kinesis → Lambda → S3 → Glue → Athena → QuickSight."

Multi-Region HA

"Design a multi-region HA architecture with Route 53 failover, cross-region RDS replicas, and Global Accelerator."

Bonus: Full MCP Configuration

Add more AWS MCP servers for a complete DevOps workflow:

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

Pro Tips

Be Specific

Include subnets, AZs, security groups, and data flow direction for better diagrams.

Iterate

Ask Q to modify diagrams: "Add Redis ElastiCache between ECS and Aurora" or "Add WAF in front of ALB."

Diagram → Code

After generating a diagram, ask: "Now generate CDK TypeScript code for this architecture." The CDK MCP server produces production-ready IaC.

All PostsGet in Touch