yanggf8/amazon-q-cli-mcp-server

Amazon Q CLI MCP Server

A Model Context Protocol (MCP) server that wraps the Amazon Q CLI, enabling MCP hosts (Claude Desktop, VS Code, Rovo Dev CLI, etc.) to interact with Amazon Q's AI capabilities.

Features

• ask_q / take_q: Chat with Amazon Q CLI for AI assistance
• q_translate: Convert natural language to shell commands
• q_status: Check Amazon Q CLI installation and configuration
• fetch_chunk: Fetch byte ranges from HTTP URLs
• Session Management: Automatic session persistence with conversation history
• Error Recovery: Intelligent retry logic with exponential backoff
• Security: Input validation, command whitelisting, and resource limits

Prerequisites

• Amazon Q CLI: Install from AWS documentation
• AWS Credentials: Configure via aws configure or environment variables
• Node.js: Version 18 or higher

Installation

From npm

npm install -g amazon-q-cli-mcp-server

From source

git clone <repository>
cd amazon-q-cli-mcp-server
npm install
npm run build
npm install -g .

Usage

Claude Desktop

Add to claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amazon-q-cli": {
      "command": "amazon-q-mcp-server",
      "args": []
    }
  }
}

Rovo Dev CLI

Add to ~/.rovodev/mcp.json:

{
  "mcpServers": {
    "amazon-q-cli": {
      "command": "amazon-q-mcp-server",
      "args": [],
      "transport": "stdio"
    }
  }
}

Note: If you encounter GLIBC version conflicts with Rovo Dev CLI, create a wrapper script:

#!/bin/bash
# Clear LD_LIBRARY_PATH to avoid conflicts
unset LD_LIBRARY_PATH
exec amazon-q-mcp-server "$@"

Then use the wrapper script path in your configuration.

Claude Code CLI

claude mcp add -s user amazon-q-cli amazon-q-mcp-server

Available Tools

ask_q / take_q

Chat with Amazon Q CLI for AI assistance.

Parameters:

• prompt (required): Question or prompt for Amazon Q
• model (optional): Model to use
• agent (optional): Agent/context profile

q_translate

Convert natural language to shell commands.

Parameters:

• task (required): Natural language description

q_status

Check Amazon Q CLI installation and configuration.

Parameters: None

fetch_chunk

Fetch byte ranges from HTTP URLs.

Parameters:

• url (required): HTTP/HTTPS URL
• start (optional): Start byte offset (default: 0)
• length (optional): Bytes to fetch (default: 65536, max: 10MB)
• headers (optional): Request headers

Troubleshooting

Normal Startup Messages

[Amazon Q MCP] init Amazon Q CLI MCP Server
[Amazon Q MCP] Amazon Q CLI MCP Server listening on stdio

Common Issues

Q CLI not found:

which q
q --version

AWS credentials:

aws configure
# or set environment variables
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_DEFAULT_REGION=us-west-2

GLIBC version conflicts (Rovo Dev CLI): Create a wrapper script that clears LD_LIBRARY_PATH before executing the server.

MCP server not starting:

• Check that the command path is correct
• Verify Node.js is accessible
• Ensure proper permissions on executable files

Development

npm run build    # Build TypeScript
npm run dev      # Watch mode
npm test         # Run tests

Architecture

MCP Host (Claude Desktop, Rovo Dev CLI, etc.)
    ↓ (MCP Protocol)
Amazon Q CLI MCP Server
    ↓ (Process execution with security)
Amazon Q CLI (`q` command)
    ↓ (AWS API calls)
Amazon Q Service

License

Apache License 2.0 - see LICENSE file for details.