Introduction

Let's face it: In most cases, drawing AWS architecture diagrams is no fun. You spend hours dragging boxes around in Lucidchart or draw.io, trying to make everything line up properly. It's hard to find proper icons for all the AWS services and requires manual work. In the end, your diagram looks like a kindergarten art project compared to the polished ones in AWS whitepapers. Or it looks good, but it doesn't matter, because when it's finished, it's already outdated.

Most of us hate this process, but we do it anyway because people need visuals. Not only stakeholders, but also developers. Documentation requires diagrams. Architecture reviews demand them. You end up with inconsistent styling across different diagrams because everyone uses different tools and templates. Looking at any Confluence of any company, you'll see that diagrams with different styles are everywhere.

Amazon Q with MCP servers tries to change this. You describe your architecture in plain English, and it generates the diagram for you. No more pixel-perfect alignment headaches or searching for the latest service icons.

At least that's the idea. 😶‍🌫️ Let's dive into the current state of the art, the pros and cons of this approach and how to get the best out of it.

What You'll Learn

I'll show you how to set up Amazon Q with two MCP servers that handle diagram generation. The AWS Diagram MCP server does the actual drawing work. The AWS Documentation MCP server provides current service information via the AWS documentation and best practices.

We'll start with basic examples like a simple web app, then move to complex multi-region setups. I'll share the prompting tricks I've learned for getting better results. We'll also talk about where this approach falls short, because it's not perfect.

AWS Lambda on One Page (No Fluff)

Skip the 300-page docs. Our Lambda cheat sheet covers everything from cold starts to concurrency limits - the stuff we actually use daily.

HD quality, print-friendly. Stick it next to your desk.

Grab the Cheat SheetPrivacy Policy

By entering your email, you are opting in for our twice-a-month AWS newsletter. Once in a while, we'll promote our paid products. We'll never send you spam or sell your data.

Why MCP Servers Matter for Diagram Generation

MCP servers give Amazon Q superpowers it doesn't have by default. Think of them as plugins that add specific capabilities.

• The diagram server knows how to create proper AWS architecture diagrams.
• The documentation server has access to current AWS service details.

Without these servers, Amazon Q can only work with whatever was in its training data. That means outdated service information and no actual diagram generation capabilities. With MCP servers, it can create diagrams using current AWS services and best practices.

This combination is powerful.

Amazon Q can look up service documentation in real-time and use that information to build accurate diagrams via an underlying tool.

Prerequisites and Setup

The following steps obviously all require that you have an AWS account & AWS Builder ID. Besides that, we'll need to install some software on your machine.

Installing Amazon Q

Amazon Q is available as a desktop app. You can download it from the Amazon Q homepage.

If you're using macOS, you can install it via Homebrew too:

brew install --cask amazon-q

Once installed, you can check that everything works properly by running q --version in your preferred terminal. You'll also need to login via q login.

Either use your AWS Builder ID for free or the pro license. In our case, we'll use the free version (which has limitations on how many requests you can make).

Installing MCP Servers

Now that we have Amazon Q installed, we can install the MCP servers. The MCP servers are available via Python packages.

This means we need to have Python and pip installed on our machine. If you don't, please first install pip via your package manager of choice.

Afterward, we can get uv (the package manager for Python) to install Python.

pip install uv
uv python install 3.12

As the MCP tool needs to render the graph, we also need to install Graphviz. It's also available via Homebrew:

brew install graphviz

Now we're ready to add the MCP servers into Q's configuration!

{
    "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
        }
    }
}

Please add the following JSON to your ~/.aws/amazonq/mcp.json file.

If you're not aware what MCP is, in a nutshell, it's a standard protocol for making AI agents talk to tools. Each MCP server is an application that tells the AI agent how to talk to it. It can offer different commands or functions. In our case for example, the diagram server provides a generate_diagram function. This function takes a description of the architecture and returns a diagram by using Python code and the Graphviz library.

Testing Your Setup

Now let's check if our setup works as expected by starting Q via q chat. You should see that Q starts and loads our added MCP servers:

If this is true, we're already ready to start creating diagrams! ✨

Running Your First Diagram Command

Let's start with a very simple example. Creating a diagram of a simple server backend.

Please create a diagram of a serverless API powered by AWS Lambda that is exposed via an API Gateway.

You should see that Q starts to work on our request by displaying Thinking... in the bottom left corner.

If Q needs to run MCP commands, it will display a message like this. You'll need to confirm the calls either via:

• y (confirm once just for this call)
• or t (to trust the call for all future calls in this session)

In the example screenshot, we can see that Q wants to run the get_diagram_examples function to get a list of available diagram examples to learn from.

Let's confirm the call and all future calls of this function via t. Q will ask for many more calls to be trusted. Let's confirm all of them.

At the end, we'll be notified that the generation was successful. It will also show where the diagram is stored. By default, it will be stored in the current directories' generated-diagrams folder.

What do we notice in our case?

We've never talked about DynamoDB, but Q did use it anyway. That's because we weren't explicit enough in our architecture description. Even if we were more precise, there's still a chance that Q will come up with something we've not specified as the output is never 100% deterministic.

Nevertheless, the result doesn't look too bad!

Configuration Options

There are a few settings that you can configure:

• Styling: Use your favorite colors and shapes.
• Format: It's possible to request other formats like SVG (PNG is the default).
• Output directory: As mentioned, everything will be stored in the generated-diagrams folder by default. It's up to you to change this.

Creating Architecture Diagrams

Let's continue with some more complex examples and see how Q handles them.

Detailed Example

Now we try to create a diagram of a three-tiered web application. In comparison to our first try, let's be way more specific.

Create a diagram of a simple three-tier web application architecture using AWS services.
Requirements:
- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.
Components:
1.	Client Layer:
	A single "User" accessing the application via a web browser (represented as an external entity, not an AWS service).
2.	Application Layer:
	One "Amazon EC2 Instance" running the web application.
3.	Database Layer:
	One "Amazon RDS Instance" (for example, using MySQL or PostgreSQL).
Connections:
- The User connects to the Amazon EC2 instance.
- The Amazon EC2 instance connects to the Amazon RDS instance.
Labels:
- Clearly label each component as follows: "User", "Amazon EC2", and "Amazon RDS".
Restrictions:
- Do not include any load balancers, VPCs, subnets, security groups, auto-scaling, caching, monitoring, IAM roles, or any other AWS or third-party services not explicitly listed above.

Instead of simply writing a text, we've structured our request properly. It's way more detailed and should get better results.

The result looks exactly as we described it. No hallucinated components, no extra services.

It's simple, but on point! Obviously, it's not a real-world layered architecture, as most details are missing like VPCs, public and private subnets, load balancers, etc.

Let's change that and add some more details.

Create a diagram of a three-tier web application architecture using AWS services.
Requirements:
- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.
Components:
1.	VPC:
	One "Amazon VPC" containing all resources.
	One "Public Subnet" within the VPC.
	One "Private Subnet" within the VPC.
2.	Client Layer:
	A single "User" accessing the application via a web browser (external to AWS).
3.	Application Layer:
	One "Application Load Balancer" in the public subnet.
	One "Amazon EC2 instance" in the public subnet, running the web application.
4.	Database Layer:
	One "Amazon RDS instance" in the private subnet.
Connections:
- The User connects to the Application Load Balancer.
- The Application Load Balancer forwards traffic to the Amazon EC2 instance.
- The Amazon EC2 instance connects to the Amazon RDS instance.
Labels:
- Clearly label each component as follows: "User", "VPC", "Public Subnet", "Private Subnet", "Application Load Balancer", "Amazon EC2", and "Amazon RDS".
Restrictions:
- Do not include any other AWS services, such as security groups, NAT gateways, internet gateways, auto-scaling, monitoring, IAM roles, or any third-party services not explicitly listed above.

Great result! We do have a little text overflow, but that's not a big deal.

Best Practices for Prompting

So what are the best practices for prompting Q for our architecture diagrams? We've already learned that we need to be specific and detailed.

Let's expand on that.

Adding Context and Requirements

The biggest mistake you can make is being vague about what you want. If you don't specify the requirements, Q will likely hallucinate components that are not part of your architecture.

We need to be precise and specific.

A good general approach is to include the sections we've used in our previous examples.

• Requirements: Specify the requirements for the diagram. This can be kept general.
• Components: List the components that should be included in the diagram. By being specific, we can avoid that Q comes up with components that do not exist in our case.
• Connections: List the connections between the components. Let's make sure the connections between components are correct.
• Labels: List the labels for the components. This might be helpful to avoid confusion and auto-generated labels that are not what you want.
• Restrictions: List the restrictions for the diagram. What should be excluded?

For the requirements, the example from our first try is a good starting point.

- Only include the AWS services and components described below.
- Do not add any extra components, services, or icons beyond what is described.

You can obviously iterate on this as long as you want to get the best results.

Using Meta Prompting

Let's do an "Inception" on our process of the creation. Why do we need to write the prompt on our own?

Let's go one level up and ask Q to create a basic prompt template we can use to create the diagram. This way, we'll likely get better results.

Let's create a prompt that I can use to create technical diagrams via Amazon Q and its diagram creation MCP.
The prompt should be very specific and make sure that Q doesn't add any components that we didn't describe.
It should be very precise and the output should be as deterministic as possible, but I don't want to explicitly describe where the components should be placed.

When we put this into Q with Sonnet 4.0, we'll get a nice prompt template that we can re-use.

Limitations and Drawbacks

Most obviously, the outputs won't be deterministic. It's also very hard to make sure that it's visually pleasing and that texts & arrows are properly placed.

Let's have a look at the examples provided by the introduction article by AWS:

Which was (at least shown in the blog), created with the following prompt:

Create a diagram for a three-tier web application with a presentation tier (ALB and CloudFront), application tier (ECS with Fargate), and data tier (Aurora PostgreSQL). Include VPC with public and private subnets across multiple AZs. Check for AWS documentation to ensure it adheres to AWS best practices before you create the diagram.

Let's reuse the exact prompt they used and see what we get.

Looks very different; we've lost some details (e.g. the ECS task role is not there anymore), but got more details regarding the availability zones. Some of the labels are not perfectly placed, but that's not a big deal.

Let's try it one more time.

Another slightly different result. As you can see, it's hard to get consistently good results.

Conclusion

Amazon Q with MCP servers for diagram generation is promising, but it's not ready to replace your existing tools completely.

Here's where it shines: You can create basic architecture diagrams quickly without hunting for icons or fighting with alignment. But the limitations are real: Every generation gives you different results, even with identical prompts. Text placement and visual formatting can be messy. You'll spend time tweaking prompts to avoid unwanted components. If you need pixel-perfect diagrams for presentations or client deliverables, stick with your current tools for now.

The future looks interesting though. As the underlying models improve and the MCP servers (and underlying tools) get more sophisticated, this approach might actually solve the diagram creation problem we all hate.

For now, consider it a useful addition to your toolkit, not a replacement.

AWS Lambda on One Page (No Fluff)

Skip the 300-page docs. Our Lambda cheat sheet covers everything from cold starts to concurrency limits - the stuff we actually use daily.

HD quality, print-friendly. Stick it next to your desk.

Grab the Cheat SheetPrivacy Policy

By entering your email, you are opting in for our twice-a-month AWS newsletter. Once in a while, we'll promote our paid products. We'll never send you spam or sell your data.