Automating AWS Architecture Diagrams and Kubernetes Manifests with Amazon Q CLI and MCP Servers: A Complete Guide

Introduction

Documenting cloud architectures and Kubernetes configurations is a critical yet often tedious task for developers, cloud architects, and DevOps teams. Traditional tools require manual effort and quickly fall out of sync with rapidly evolving infrastructure. Amazon Q CLI and Model Context Protocol (MCP) servers a powerful combination automate the creation of AWS architecture diagrams and Kubernetes manifests directly from natural language prompts.

This guide walks you through every step, from installation to troubleshooting, so you can generate professional diagrams and manifests with minimal effort and maximum consistency.

1. What Are Amazon Q CLI and MCP Servers?

Amazon Q CLI is a generative AI-powered assistant for the command line, designed to streamline cloud workflows. It supports the Model Context Protocol (MCP), an open standard that enables AI models to interact with external tools and services. MCP servers act as modular backends that process specific requests like generating diagrams, creating Kubernetes manifests, or analyzing AWS costs using structured data and code.

2. Why Use Amazon Q CLI and MCP for Automation?

• Automation: Generate diagrams and manifests from natural language prompts, reducing manual work.

• Consistency: Keep documentation in sync with your actual infrastructure.

• Scalability: Easily update diagrams and manifests as your architecture evolves.

• Collaboration: Share diagrams and manifests with your team or embed them in documentation.

• Best Practices: Built-in security and scalability defaults for Kubernetes manifests.

3. Step-by-Step Setup

3.1. Install Amazon Q CLI on macOS

You can install Amazon Q CLI using Homebrew or by downloading the desktop app. Here’s the Homebrew method:

# Install Homebrew if you don't have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Amazon Q CLI
brew install amazon-q

# Open the Amazon Q app to enable shell integration
open /Applications/Amazon\ Q.app

# Follow the prompts to enable shell integration and authenticate

After installation, restart your terminal and verify the installation:

q --version

3.2. Authenticate with Amazon Q

Authenticate using your AWS Builder ID or IAM Identity Center credentials:

q login

Follow the prompts to complete authentication.

3.3. Set Up a Python Virtual Environment

Amazon Q and MCP servers often require specific Python versions and dependencies. Create a virtual environment for isolation:

# Install Python 3.12 (required by many MCP servers)
brew install python@3.12

# Create and activate a virtual environment
python3.12 -m venv mcp-env
source mcp-env/bin/activate

3.4. Install Required Dependencies

Install Graphviz for diagram rendering and uv for package management:

brew install graphviz
pip install uv

3.5. Install MCP Servers

Use uv to install MCP servers inside your virtual environment:

uv pip install awslabs.aws-diagram-mcp-server
uv pip install awslabs.cdk-mcp-server
uv pip install kubernetes-mcp-server

If you encounter issues, check the official documentation for alternative installation methods or Docker images.

3.6. Configure MCP Servers

Create or edit the MCP configuration file at ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "awslabs.cdk-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.cdk-mcp-server"],
      "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
    },
    "kubernetes-mcp-server": {
      "command": "uvx",
      "args": ["kubernetes-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

3.7. Launch Amazon Q CLI and Check MCP Server Status

Start Amazon Q CLI:

Check which MCP servers are loaded and available:

/tools

You should see output indicating that your MCP servers are initialized and ready to use.

4. Generating AWS Architecture Diagrams

4.1. Craft Your Prompt

In the Amazon Q CLI chat, enter a natural language prompt to generate your diagram. For example:

Generate a simple AWS architecture diagram showing a web application with Amazon API Gateway, AWS Lambda, and Amazon RDS. Output the diagram as a PNG image.

4.2. Approve Tool Actions

When prompted to allow the tool, type:

• y to allow this action once.

• t to always trust this tool for the session.

4.3. Locate and Share Your Diagram

After successful generation, your diagram will be saved to:

~/.aws/amazonq/generated-diagrams/web_app_architecture.png

5. Generating Kubernetes Manifests

5.1. Craft Your Prompt

In the Amazon Q CLI chat, enter a natural language prompt to generate a Kubernetes manifest. For example:

6. Troubleshooting and Best Practices

6.1. Common Issues

• No q command found: Ensure shell integration is enabled via the Amazon Q app.

• MCP config errors: Remove comments and validate JSON syntax in mcp.json.

• Python version conflicts: Use Python 3.10–3.12 in a virtual environment.

• Missing dependencies: Install Graphviz and uv.

• Tool not trusted: Approve tool actions when prompted.

• Diagram/manifest not generated: Check logs and retry with corrected code.

6.2. Best Practices

• Use virtual environments to avoid dependency conflicts.

• Regularly update your MCP servers and Amazon Q CLI.

• Back up your configuration before making changes.

• Monitor logs for errors and warnings.

• Share your workflow with your team to standardize documentation.

• Test manifests in a staging environment before production.

7. Behind the Scenes: How It Works

When you submit a prompt to Amazon Q CLI, it identifies the request and activates the appropriate MCP server. For diagrams, the MCP server generates Python code using the diagrams library and renders the diagram as a PNG image using Graphviz. For manifests, the Kubernetes MCP server generates YAML based on your prompt. The output is returned to Amazon Q, which presents it to you.

8. Example: Generating a 3-Tier Architecture Diagram

Here’s another example prompt for a more complex architecture:

Generate an AWS architecture diagram for a 3-tier web application with Amazon API Gateway, AWS Lambda, Amazon RDS, and Amazon S3. Output the diagram as a PNG image.

Amazon Q CLI will handle the rest, producing a professional diagram in minutes.

9. Extending Amazon Q with Custom MCP Servers

You can create your own MCP servers to extend Amazon Q’s capabilities. For example, you could build a server that interacts with AWS services, analyzes logs, or automates deployments. The process involves defining your server’s capabilities in mcp.json and integrating it with Amazon Q CLI.

10. Conclusion

Automating AWS architecture diagrams and Kubernetes manifests with Amazon Q CLI and MCP servers transforms manual, error-prone processes into streamlined, code-driven workflows. By following this guide, you can generate, update, and share professional diagrams and manifests with ease, keeping your documentation in sync with your infrastructure and empowering your team to focus on innovation.