For many professionals, the task of crafting AWS architecture diagrams can be tedious and time-consuming. Traditional approaches often involve manually placing elements in tools like Lucidchart or draw.io, requiring meticulous alignment and manual icon selection. Such diagrams frequently appear inconsistent across organizations and quickly become outdated, creating a challenge for both stakeholders and developers needing accurate documentation and visuals.

Amazon Q, enhanced by Model-Compute Protocol (MCP) servers, aims to revolutionize this process. By allowing users to describe cloud architectures in plain English, Amazon Q produces diagrams automatically—removing the hassle of finding icons or chasing perfect alignment.

This article explains how to configure Amazon Q with two MCP servers for diagram generation and documentation. The AWS Diagram MCP server creates the visual diagrams, while the AWS Documentation MCP server supplies up-to-date AWS service details and best practices. Readers can expect practical walkthroughs for building simple web app diagrams and more complex multi-region architectures, alongside proven techniques for effective prompt creation. Limitations of this method are also examined, providing a clear picture of when the tool is most useful.

The Value of MCP Servers

MCP servers extend Amazon Q’s capabilities far beyond its standard functions. Essentially, these servers act as plugins:

• The diagram server crafts accurate AWS architecture diagrams.
• The documentation server keeps information on AWS services current.

Without these servers, Amazon Q is limited to what it already knows, resulting in outdated diagrams and no actual drawing functionality. By connecting MCP servers, users benefit from the most recent AWS services and architectural best practices, enabling Amazon Q to generate diagrams that reflect reality.

Setup Prerequisites

To get started, an AWS account and AWS Builder ID are essential. Additional setup requires installing several software packages.

Installing Amazon Q

Amazon Q can be downloaded as a desktop application from the Amazon Q homepage. For macOS users, installation is available through Homebrew:

textbrew install --cask amazon-q

After installation, use the terminal command q --version to confirm successful deployment and login using q login. Both free and pro licenses are available, though the free tier has usage limitations.

Installing MCP Servers

The MCP servers are available as Python packages, necessitating Python and pip. After installing pip, obtain uv (a Python package manager):

textpip install uv
uv python install 3.12

For diagram rendering, Graphviz is required and can also be installed via Homebrew:

textbrew install graphviz

Once prerequisites are in place, configure MCP servers in Q by adding the following JSON to the ~/.aws/amazonq/mcp.json file:

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

This configuration empowers Amazon Q to interact with the MCP servers through the MCP protocol, expanding its range of actions.

Testing the Setup

To test the configuration, start Amazon Q via the q chat command. When the servers are recognized, users can begin issuing diagram prompts immediately.

First Diagram Generation

A basic example involves requesting a serverless API architecture using AWS Lambda and API Gateway. Upon submitting the prompt, Amazon Q processes the request and activates any necessary functions. If additional confirmations are required, users can approve them for seamless operation.

One important takeaway is that Amazon Q may introduce components that were not explicitly mentioned, such as DynamoDB, if the description lacks detail. Results are generally reliable but not entirely deterministic.

Customizing and Outputting Diagrams

Users can adjust settings like styling, output format (PNG or SVG), and the default directory for generated diagrams (usually “generated-diagrams”). Testing with more complex diagrams, such as a three-tier web application, highlights the importance of detailed instruction. For example, specifying all required AWS components and connections ensures accuracy and prevents extraneous services from appearing.

Prompting Best Practices

Effective prompting is crucial. The recommendation is to clearly outline all requirements, components, connections, labels, and restrictions for each diagram. Templates that spell out these sections help Amazon Q create visuals that conform precisely to user expectations.

Moreover, using meta prompts—requests that generate reusable prompt templates—can dramatically improve consistency and efficiency across multiple diagram creation projects.

Limitations and Drawbacks

Despite the promise, this automated approach has notable drawbacks:

• Output diagrams are not fully deterministic; results may vary from one generation to the next.
• Text placement and overall visual polish may not match hand-crafted diagrams.
• Manual prompt refinement is sometimes required to avoid unwanted or missing elements.

Because of these limitations, this method is best suited for rapid prototyping or documentation drafts, not for final production diagrams needing pixel-perfect quality.

Conclusion

While Amazon Q with MCP servers simplifies the creation of AWS architecture visuals, it is currently best considered a helpful supplement to, rather than a replacement for, traditional diagramming tools. The technology offers a glimpse into a future where architecture diagramming is effortless and automated, though for now, expert-designed visuals remain necessary for polished, client-facing presentations. As the underlying AI and MCP tools evolve, expect this process to become an increasingly valuable asset for all cloud architecture professionals.

Read more such articles from our Newsletter here.