DEV Community

Cover image for Getting Started with Amazon Q CLI and AWS MCP Servers on Windows
Swetha Mudunuri
Swetha Mudunuri

Posted on • Edited on

Getting Started with Amazon Q CLI and AWS MCP Servers on Windows

#amazon #amazonqcli #codeassitant #mcp

If you're curious about how to bring generative AI to your terminal and enhance it with contextual awareness of AWS services, this blog walks you through setting up Amazon Q CLI on a Windows environment and connecting it to one or more MCP (Model Context Protocol) servers.

Whether you're experimenting with infrastructure as code, checking AWS best practices, or planning cost analysis, MCP gives Amazon Q the power to understand your environment better.

What’s Amazon Q CLI and MCP?
Amazon Q CLI is a command-line tool that lets you interact with a generative AI assistant directly in your terminal. Think of it as having a smart AWS-AI assistant that can help with commands, code generation, documentation lookup, and much more.

MCP (Model Context Protocol) is an open protocol that connects AI tools like Q CLI to external services — such as AWS documentation, CDK best practices, cost calculators, or even image generators. MCP servers provide that real-time context the model might not have, especially for newer APIs or service updates.

🏗️ Amazon Q CLI Architecture

  1. You interact with Q CLI
    – You enter natural language or AWS-related commands into your terminal.

  2. Q CLI handles your session
    – It handles AWS authentication and keeps track of your session.

  3. It checks what you’re asking for
    – Q CLI checks whether you're requesting an AWS action, a local file operation, or AI help.

  4. It connects to AWS services or your local files
    – It either runs AWS commands or interacts with your local file system, based on the request.

  5. If your request needs AI understanding
    – For natural language or complex tasks, Q CLI calls Amazon’s large language model (LLM) to assist.

  6. Q CLI looks for any available MCP tools
    – It checks for any local MCP servers that are available and relevant to your request

  7. Relevant parts of the request are sent to MCP servers
    – Q CLI sends parts of the request to the appropriate MCP tools for specialized processing.

  8. MCP tools send back results or extra context
    – These tools provide extra context or project-specific output to support your query.

  9. Final response is shown in your terminal
    – The final result whether its from AWS, local systems, AI, or MCP tools—is provided in your terminal.

Amazon_Q_CLI_&_MCP_Integration

Each MCP server you configure exposes a specific domain of knowledge. You can connect multiple MCP servers depending on your use case.

How to setup Amazon Q CLI on Windows (via WSL)

Since Amazon Q CLI is Linux-based, you'll need to use the Windows Subsystem for Linux (WSL) to run it on a Windows machine. Follow these steps:

✅ Step 1: Install WSL on Windows ( I am using Visual Studio Terminal for installation)
Open PowerShell and run:

wsl --install
Enter fullscreen mode Exit fullscreen mode

Ubuntu-Installation

  • This installs Ubuntu by default.
  • During installation, you’ll be prompted to set a username and password for the Linux environment.

✅ Step 2: Download the Amazon Q CLI Installer
From your WSL terminal, download the appropriate zip file for your Linux distribution.

For Linux x86-64, run:

curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.q.us-east-1.amazonaws.com/latest/q-x86_64-linux.zip" -o "q.zip"
Enter fullscreen mode Exit fullscreen mode

✅ Step 3: Install Dependencies
Before proceeding, make sure required packages are installed:

sudo apt get install unzip
Enter fullscreen mode Exit fullscreen mode

✅ Step 4: Extract the Q CLI Package
Unzip the downloaded file:

unzip q.zip
Enter fullscreen mode Exit fullscreen mode

✅ Step 5: Install Amazon Q CLI
Run the install script:

q/install.sh
Enter fullscreen mode Exit fullscreen mode
  • During installation, you'll be asked to provide:
  • Shell Config Modification: Select Yes to allow the script to update your shell configuration automatically.
  • Login Method: Choose "Use for Free with Builder ID"-Authenticate using your Builder ID. Amazon-Q-Installation

✅ Step 6: Relaunch and Verify Setup

  • Close the terminal after installation is complete.
  • Relaunch the terminal and log back into your Ubuntu (WSL) environment.
  • Run the following command to verify that Amazon Q CLI is installed correctly: 
wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode 
q --version
Enter fullscreen mode Exit fullscreen mode

For official documentation, refer to: Amazon-Q-CLI Installation Guide

MCP Server Configuration with Amazon Q CLI
Now that Amazon Q CLI is installed, let’s proceed with setting up the MCP Server.

Prerequisites for MCP Server Installation

🔹 Step 1: Install uv
Install uv using curl:

curl -LsSf https://astral.sh/uv/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

ℹ️ Other installation methods (e.g., using pip) are also available — refer GitHub Repository for details.

🔹 Step 2: Verify uv Installation

uv --version
Enter fullscreen mode Exit fullscreen mode

🔹 Step 3: Install Python 3.10 Using uv

uv python install 3.10
Enter fullscreen mode Exit fullscreen mode

🔹 Step 4: Ensure AWS CLI is Installed

Check if AWS CLI is installed:

aws --version
Enter fullscreen mode Exit fullscreen mode

If not, install it using:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
Enter fullscreen mode Exit fullscreen mode

Then configure credentials:

aws configure
Enter fullscreen mode Exit fullscreen mode

Make sure your IAM role/user has permissions to use AWS MCP services (like access to the AWS Pricing API).

🔹 Step 5: Install Required Packages for MCP

Some MCP servers (like AWS Diagram MCP Server) need tools like GraphViz. Install it:

sudo apt-get install graphviz
Enter fullscreen mode Exit fullscreen mode

🗂️MCP Configuration in Amazon Q

Step 6: Create MCP Configuration Folder and File
Create the necessary folder:

Now we need to create a folder amazon q under ~/.aws

mkdir -p ~/.aws/amazonq
cd ~/.aws/amazonq
Enter fullscreen mode Exit fullscreen mode

Create and edit the mcp.json file:

{
  "mcpServers": {
    "awslabs.nova-canvas-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.nova-canvas-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "**your-aws-profile**",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Don't forgot to change your ur profile details.

🔁 You can configure multiple MCP servers by listing them under "mcpServers" like so:

{
  "mcpServers": {
    "mcpserver1": { ... },
    "mcpserver2": { ... }
  }
}
Enter fullscreen mode Exit fullscreen mode

🚀 Launch Amazon Q

Amazon-q-terminal

You’ll now be logged into the Amazon Q CLI with your configured MCP servers.

I've set up four MCP servers — nova-canvas, cost-analysis, aws-diagram, and document. The cover image was generated using the nova-canvas server, while the architecture diagram below was created using the aws-diagram MCP server

Amazon-q-architecture-diagram

Security Considerations

  • All communication between the CLI and AWS services is secured via HTTPS
  • Authentication is handled through IAM
  • Local file system and command execution is limited to the user's permissions
  • MCP servers operate within the user's environment with appropriate access controls

References
GitHub link for AWS MCP servers
AWS-Cli-Installation
AWS-Cli-User-Guide

Thank you for reading!!!!!!

Top comments (2)

Collapse
 
abinaya_sv_56acb826629f0f profile image
Abinaya SV •

Good article swetha

Collapse
 
swethamudunuri profile image
Swetha Mudunuri •

Thank you Abi.