Hello everyone,

Of course, the title is just a joke. I gave this title for a reason that you’ll understand as you go further into the article.

In this article, I’ll highlight Amazon Q Developer CLI + MCP, because as someone who primarily works in AWS cloud, I constantly need to create architectural diagrams. In today’s era, where generative AI is so popular, manually dealing with diagrams has become unnecessarily time-consuming. That’s why I started looking for a cloud-native solution, and among the options I tried, let me introduce you to the one that impressed me the most:

-> Amazon Q Developer CLI + MCP (Model Context Protocol)

Amazon Q Developer CLI is a command line interface that brings the generative AI capabilities of Amazon Q directly to your terminal. Developers can interact with Amazon Q through natural language prompts, making it an invaluable tool for various development tasks.

Of course, Amazon Q itself is not a brand-new product. It was introduced in 2023, while Amazon Q Developer CLI was launched in 2024. However, as announced in April 2025, MCP enables Amazon Q Developer to connect with specialized servers that extend its capabilities beyond what’s possible with the base model alone. MCP servers act as plugins for Amazon Q, providing domain-specific knowledge and functionality. The AWS Diagram MCP server specifically enables Amazon Q to generate architecture diagrams using the Python diagrams package, with access to the complete AWS icon set and architectural best practices. Without dragging this out any further, let’s dive into the technical content.

Prerequisites

  • To implement this solution, you must have an AWS account with appropriate permissions.
  • You must have Python 3.10.x or higher.

Set up your environment

Before you can start creating diagrams, you need to set up your environment with Amazon Q CLI, the AWS Diagram MCP server, and AWS Documentation MCP server. This section provides detailed instructions for installation and configuration.

Install Amazon Q Developer CLI

  1. Download and install Amazon Q Developer CLI. For instructions:
    -> https://aws.amazon.com/tr/developer/learning/q-developer-cli/
  2. Verify the installation by running the following command: q --version
    You should see output similar to the following: Amazon Q Developer CLI version 1.x.x
  3. Configure Amazon Q CLI with your AWS credentials: q login
  4. Choose the login method suitable for you:

Set up MCP servers

Complete the following steps to set up your MCP servers:

  1. Install uv using the following command: pip install uv
  2. Install GraphViz for your operating system.
  3. 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 automatically discovers MCP servers in the ~/.aws/amazonq/mcp.json file.

Understanding MCP server tools

The AWS Diagram MCP server provides several powerful tools:

  • list_icons – Lists available icons from the diagrams package, organized by provider and service category
  • get_diagram_examples – Provides example code for different types of diagrams (AWS, sequence, flow, class, and others)
  • generate_diagram – Creates a diagram from Python code using the diagrams package

The AWS Documentation MCP server provides the following useful tools:

  • search_documentation – Searches AWS documentation using the official AWS Documentation Search API
  • read_documentation – Fetches and converts AWS documentation pages to markdown format
  • recommend – Gets content recommendations for AWS documentation pages

These tools work together to help you create accurate architecture diagrams that follow AWS best practices.

“This is the part where the gates of heaven officially open.
Open your terminal and just type q chat.”

For example, write the following prompt for the demo. Before doing this, make sure that the MCP server load above has been completed successfully.

Create a diagram for an e-commerce platform with microservices architecture. Include components for product catalog, shopping cart, checkout, payment processing, order management, and user authentication. Ensure the architecture follows AWS best practices for scalability and security. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

Along the way, it’ll ask for your confirmation a few times just hit ‘t’ to keep going. The cool part is, you actually get to watch what it’s doing and which pieces of content it’s checking. Based on the prompt you give, it spins up an architecture that leans on AWS best practices and governance. Honestly, this is one of my favorite parts.


And ta-daa, here’s the sample diagrams:

With the comprehensive prompt details you provide and -the more specific distinctions you make- the diagram can become much more detailed and professional. Just like the output above, you can also find additional content in AWS’s blog posts.

And of course, with MCP you can do far more than just AWS architecture diagrams. In this piece, I referenced AWS diagrams both for the fun of it and to showcase this feature.

I also came across the following content about exporting the diagram you’ve created as a .drawio file, but I haven’t yet managed to get a proper output from it as a prompt. Once I do, I’ll update this section as well.

-> Modernize Legacy AWS Architecture Diagrams with Amazon Q CLI, MCP Server, and draw.io

I hope these article help save you time.

References: