Ssri7774/q-cli-aws-diagram-mcp

Setting Up AWS Diagram MCP Server for Amazon Q CLI

This guide provides step-by-step instructions for installing and configuring the AWS Diagram MCP Server for use with Amazon Q CLI.

Prerequisites

1. Linux operating system
2. Python 3.10 or higher
3. pip package manager
4. GraphViz (required for diagram generation)

Installation Methods

You can install the AWS Diagram MCP Server using either the automated script or by following the manual installation steps.

Option 1: Automated Installation Script (Recommended)

For a hassle-free installation, you can use our automated installation script:

# Download the installation script
curl -O https://raw.githubusercontent.com/Ssri7774/q-cli-aws-diagram-mcp/main/docs/aws-diagram-mcp/install_aws_diagram_mcp.sh

# Make it executable
chmod +x install_aws_diagram_mcp.sh

# Run the script
./install_aws_diagram_mcp.sh

The script will:

• Check for prerequisites
• Install GraphViz
• Install required Python packages
• Create and configure the MCP configuration file
• Verify the installation

Script Features

• Detects your system's package manager (apt, yum, dnf, brew)
• Provides colored output for better readability
• Verifies each step of the installation
• Works on various Linux distributions and macOS
• Provides clear error messages and troubleshooting guidance

Option 2: Manual Installation Steps

If you prefer to install manually or need more control over the installation process, follow these steps:

1. Install GraphViz

GraphViz is required for generating diagrams. Install it using your system's package manager:

sudo apt-get update && sudo apt-get install -y graphviz

For other operating systems, refer to the GraphViz download page.

2. Install Required Python Packages

Install the necessary Python packages:

# Install the diagrams package
pip install diagrams

# Install the MCP tools
pip install fastmcp uvx

# Install the AWS Diagram MCP Server
pip install awslabs.aws-diagram-mcp-server

3. Create MCP Configuration Directory

Create the directory structure for the Amazon Q CLI configuration:

mkdir -p ~/.aws/amazonq

4. Create MCP Configuration File

Create the MCP configuration file at ~/.aws/amazonq/mcp.json with the following content:

cat > ~/.aws/amazonq/mcp.json << 'EOF'
{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-diagram-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "autoApprove": [],
      "disabled": false
    }
  }
}
EOF

Verification

To verify that the AWS Diagram MCP Server is properly installed and configured:

1. Start Amazon Q CLI:

   q chat
   

2. Ask Amazon Q to create a simple diagram:

   Create a simple AWS architecture diagram with an EC2 instance and an S3 bucket
   

3. Amazon Q should use the AWS Diagram MCP Server to generate the diagram.

Troubleshooting

Common Issues

1. GraphViz Not Found Error:

   • Error: graphviz.backend.execute.ExecutableNotFound: failed to execute PosixPath('dot')
   • Solution: Install GraphViz using your system's package manager.

2. Python Version Issues:

   • Error: Package incompatibility messages
   • Solution: Ensure you're using Python 3.10 or higher. Check with python3 --version.

3. Permission Issues:

   • Error: Permission denied when creating directories or files
   • Solution: Use sudo for system-wide installations or ensure proper permissions for user directories.

4. MCP Server Not Detected:

   • Issue: Amazon Q doesn't use the diagram capabilities
   • Solution: Verify the MCP configuration file path and content. Restart the Amazon Q CLI.

Additional Configuration Options

Using Docker (Alternative Method)

If you prefer using Docker, you can configure the MCP server to run in a container:

{
  "mcpServers": {
    "awslabs.aws-diagram-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "FASTMCP_LOG_LEVEL=ERROR",
        "awslabs/aws-diagram-mcp-server:latest"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Note: This requires building or pulling the Docker image first.

Adjusting Log Levels

You can change the log level by modifying the FASTMCP_LOG_LEVEL environment variable in the configuration file. Available options are:

• ERROR (default)
• WARNING
• INFO
• DEBUG

Resources

• AWS MCP Documentation
• Diagrams Python Package
• GraphViz Documentation

This setup enables Amazon Q to create various types of diagrams including AWS architecture diagrams, sequence diagrams, flow diagrams, and class diagrams using Python code.