Architecture Diagram: Local Development with Amazon Q + WSL (Ubuntu) + MCP Server for Application Modernization
Amazon Q Developer is your AI-powered coding assistant designed to supercharge productivity for developers working on AWS. Think of it as a contextual, cloud-native co-pilot that not only answers your questions but also helps write, debug, and modernize code right inside your IDE.
Amazon Q Developer (Free Tier)
✅ Natural language Q&A on AWS services and cloud development.
✅ Code generation & explanations in supported languages.
✅ AWS documentation search from within your IDE.
✅ Works across local, AWS Builder ID-linked environments.
Amazon Q Developer (Pro Tier)
✅ Amazon Q Code Transformation: Convert legacy Java apps to modern Java on AWS (Spring Boot + Lambda, etc.)
✅ Deep application analysis and modernization recommendations.
✅ Interactive code generation with context-aware chat.
✅ Enterprise-ready with SSO support and advanced integrations.
In Visual Studio Code, how can I install the Amazon Q extension?
Available for Windows, macOS, and Linux, Visual Studio Code is a desktop source code editor that is both lightweight and powerful. Make sure Visual Studio Code is installed on your computer. The setup instructions are available in their official manual.
What if you already have Amazon Q and the AWS Toolkit? How can that be updated?
Update the AWS Toolkit if you have already done so. If you have Amazon Q connections, the new Amazon Q extension will be deployed for you immediately, even if they are expired.
There are two ways for you to log in, and this blog examines both of them:
1. With Builder ID docs for individual users using AWS’s Free Tier
2. IAM Identity Center with Pro Tier for Professional Users
You can represent your work-self with a workforce identity in IAM Identity Center and your private-self with an AWS Builder ID. These identities function on their own. For more information, see Amazon Q Developer Pricing.
This article focuses exclusively on the Amazon Q Developer Free Tier, highlighting the powerful features available at no cost. With the Free Tier, developers can ask natural language questions, generate architecture diagrams, explore code, and interact with AWS services — all from the terminal or VS Code. While Amazon Q Pro offers advanced features like code transformation, this guide is tailored for those getting started with the free version, making it ideal for learners, hobbyists, and early-stage cloud developers.
Without requiring an AWS account, using the AWS Builder ID
To utilize Amazon Q for free, select this option. You must create an AWS Builder ID even if you do not require an AWS account. Access to specific tools and services is granted by an individual’s AWS Builder ID. Free is the AWS Builder ID. In contrast to Builder ID, you only pay for the AWS resources you use in your AWS accounts. You can use the same email address for both your AWS Builder ID and an AWS account’s root user email.
- Click “Continue” after choosing the first “Use for Free” option in step 1.
- Click “Proceed to browser” when a pop-up window containing a confirmation code appears.
- It will take you to a web browser. Click “Confirm and continue” after making sure the code is the same.
- This takes you to the AWS Builder ID sign-up or sign-in page. The sign-up screen will be bypassed if you are already logged into Builder ID.
- Permit the IDE extensions to access AWS services.
After finishing, you can return to your IDE. Using your Builder ID, you have successfully signed into Amazon Q. You should see a Q Chat window open automatically.
click on “Amazon Q” in the status bar below. For other options, such as pausing auto-suggestions, opening settings, or signing out.
Started with WSL and Ubuntu: A Developer’s Local
For developers working on cloud-native applications, having a Linux-like environment on a Windows machine can be a game-changer. That’s where WSL (Windows Subsystem for Linux) comes in.
With WSL + Ubuntu, you get the best of both worlds: the power and familiarity of Linux tools and the convenience of Windows. No need for dual-booting or spinning up a virtual machine — WSL gives you a lightweight Linux environment directly inside Windows, perfect for development, automation, and working with cloud platforms like AWS.
In this article, we’ll explore how to:
- Set up WSL with Ubuntu on your Windows machine.
- Use it for local development and scripting.
- Seamlessly integrate it with Amazon Q and MCP Server for cloud modernization workflows.
The command refreshes the list of available packages and their versions from the repositories, ensuring your system knows about the latest software updates.
sudo apt-get update
The command installs the libfuse2 library, which is needed to run applications (like AppImage files) that rely on the FUSE (Filesystem in Userspace) interface.
sudo apt install libfuse2
This command downloads the latest Amazon Q .deb installer securely using curl and saves it as amazon-q.deb for installation on Debian-based systems.
curl — proto ‘=https’ — tlsv1.2 -sSf https://desktop-release.q.us-east-1.amazonaws.com/latest/amazon-q.deb -o amazon-q.deb
This command installs the downloaded Amazon Q .deb file using apt, enabling Amazon Q on your system.
sudo apt install -y ./amazon-q.deb
To access Amazon Q Developer, create a BuilderID here and then enter the command.
q login
Once logged in, just type q in the terminal to start using Amazon Q.
q
After following the above steps, you’ll have Amazon Q successfully installed and running on your system. By updating your package list, installing required dependencies like libfuse2, and downloading the latest .deb file, you’ve set up the environment smoothly. Once the installation completes, simply launch Amazon Q by typing itq in your terminal. After logging in with your AWS Builder ID, you’re ready to interact with Amazon Q right from your local machine—ask questions, get code suggestions, and streamline your development workflow with ease.
MCP Support on Amazon Q CLI
Amazon Q CLI now includes powerful support for Model Context Protocol (MCP)—a framework designed to assist in the automated modernization of legacy applications. MCP acts as a control plane that coordinates various tools and services involved in analyzing, transforming, and migrating applications to AWS-native architectures.
With MCP support in Amazon Q CLI, developers can:
- Scan and assess legacy Java applications
- Get AI-powered modernization recommendations
- Automate transformations (e.g., move to Spring Boot, Lambda, or containers)
- Seamlessly manage the modernization workflow — all from the terminal
This integration allows you to harness the full potential of Amazon Q’s intelligence and the structure of MCP, enabling a streamlined, developer-friendly approach to application modernization.
To install the Astral UV runtime via Snap with classic confinement.
sudo snap install astral-uv --classic
create a file called mcp.jsonin~/.aws/amazonq
- create a file : vim mcp.json . A powerful text editor used to create or edit files in the terminal.
vim mcp.json
- A simple command used to display the contents of a file.
cat mcp.json
{
"mcpServers" : {
"awslabs.cdk-mcp-server": {
"command": "uvx",
"args": ["awslabs.cdk-mcp-server@latest"],
"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
}
}
}Vim is a powerful, keyboard-based text editor commonly used in Linux environments.
To open/edit a file:
vim filenameTo enter insert mode (to start typing):
PressiTo save and exit:
PressEsc, then type:wqand hitEnterTo exit without saving:
PressEsc, then type,:q!and hitEnter
Servers still loading …. 2 mcp servers initialized.
- awslabsaws_diagram_mcp_server
- awslabscdk_mcp_server
- Check the command ‘uvx.’
Successfully Initialized:
awslabs/aws-diagram-mcp-server
- Provides architecture diagrams and visual workflows for the MCP Server to help you understand the modernization process end-to-end.
awslabs/cdk-mcp-server
- Contains AWS CDK (Cloud Development Kit) constructs and templates to deploy the MCP Server and related components on your AWS environment.
GitHub repo here awslabs/mcp
The above repositories have been successfully initialized within Amazon Q, enabling you to:
- Visualize and interact with MCP server architecture using Amazon Q
- Use CDK-based templates to deploy and test modernization workflows
- Leverage AI-powered guidance from Amazon Q to navigate, understand, and modernize your applications
All are set now. Start the prompt in Amazon Q.
Amazon Q — Prompting in the Terminal
After launching Amazon Q using the q command in your terminal, you can enter natural language queries.
Prompt:
Launch and connect to an EC2 instance, Create your very own Kubernetes cluster, Monitor cluster creation with CloudFormation.Access your cluster using an IAM access entry make its simple basic diagramAmazon Q Response (Terminal Output):
I'll help you create a simple diagram for launching an EC2 instance, creating a Kubernetes cluster, monitoring it with CloudFormation, and accessing
it with IAM. Let me create that for you.
🛠️ Using tool: generate_diagram (trusted) from mcp server awslabsaws_diagram_mcp_server
⋮
● Running generate_diagram with the param:
⋮ {
⋮ "arguments": {
⋮ "code": "with Diagram(\"Simple Kubernetes Cluster Setup\", show=False, direction=\"LR\"):\n # User starting point\n user = User(\"DevOps Engineer\")\n \n # AWS Cloud resources\n with Cluster(\"AWS Cloud\"):\n # EC2 instance for management\n ec2 = EC2(\"Bastion Host\")\n \n # EKS Kubernetes cluster\n eks = EKS(\"Kubernetes Cluster\")\n \n # Worker nodes\n with Cluster(\"Worker Nodes\"):\n workers = [EC2(\"Node 1\"), \n EC2(\"Node 2\")]\n \n # CloudFormation for deployment\n cfn = Cloudformation(\"CloudFormation\")\n \n # IAM for access control\n iam = IAM(\"IAM Role\")\n \n # Flow connections\n user >> ec2\n user >> iam\n iam >> eks\n cfn >> eks\n cfn >> workers\n eks >> workers",
⋮ "filename": "simple_kubernetes_setup",
⋮ "workspace_dir": "/home/dd"
⋮ },
⋮ "name": "generate_diagram"
⋮ }
⋮
● Completed in 0.455s
## 🛠️ Using tool: fs_read (trusted)
⋮
● Reading images:
/home/dd/generated-diagrams/simple_kubernetes_setup.png
⋮
● Completed in 0.0s
The diagram shows a simple Kubernetes cluster setup in AWS Cloud. Here's what it illustrates:
1. A DevOps Engineer (you) is the starting point, connecting to three key components:
• A Bastion Host (EC2 instance) for secure remote access to your infrastructure
• IAM Role for authentication and authorization
• CloudFormation for infrastructure deployment
2. The CloudFormation stack provisions and manages:
• The Kubernetes Cluster (Amazon EKS)
• Worker Nodes (EC2 instances running in a cluster)
3. The IAM Role connects to the Kubernetes Cluster, enabling secure access using AWS IAM authentication
4. The Kubernetes Cluster manages the Worker Nodes (Node 1 and Node 2)
This architecture follows AWS best practices by:
• Using a bastion host for secure access
• Implementing IAM for authentication
• Using CloudFormation for infrastructure as code
• Deploying worker nodes in a cluster for high availability
This simple setup provides all the essential components needed to launch, connect to, and manage a Kubernetes cluster on AWS while maintaining
security and following infrastructure as code principles.
This prompt shows how you can use Amazon Q like a developer co-pilot in the terminal. By entering a clear query, Q:
- Understands your local environment (WSL + Ubuntu)
- Connects the flow from your local system, through Amazon Q CLI, into the MCP Server, and finally to AWS services
- Automatically generates a clear, labeled architecture diagram to visualize the full modernization path
Reference link :
Thank you for taking the time to read my article! If you found it helpful, feel free to like, share, and drop your thoughts in the comments —I’d love to hear from you.
