AWS Architecture Scanner MCP Server

Scans AWS environments and generates professional architecture diagrams showing VPC networking, compute, storage, and security resources.

Features

Scans the following AWS resources:

VPC Networking:

• VPCs with CIDR blocks
• Public and private subnets across availability zones
• Internet Gateways
• NAT Gateways
• Route tables and routing configuration
• Security Groups

Compute:

• EC2 instances (running and stopped)
• ECS clusters with task counts
• EKS clusters with versions
• Lambda functions with VPC configuration

Storage:

• S3 buckets (region-filtered)
• RDS database instances
• EFS file systems
• EBS volumes attached to instances

Diagram Generation:

Creates professional PNG or SVG architecture diagrams using the Python diagrams library with official AWS icons showing:

• VPC boundaries and CIDR blocks
• Subnet grouping by type (public/private) and AZ
• Network connectivity (IGW → public subnets, NAT → private subnets)
• Compute resources placed in appropriate subnets
• Storage services with connections
• Visual hierarchy and clustering

Installation

1. Install Python dependencies

cd ~/.mcp-servers/aws-architecture-scanner
pip3 install -r requirements.txt

2. Install Graphviz (required by diagrams library)

macOS:

brew install graphviz

Ubuntu/Debian:

sudo apt-get install graphviz

Windows: Download from https://graphviz.org/download/

3. Configure AWS credentials

Ensure AWS credentials are configured:

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-east-1"

4. Add to Claude Code MCP settings

Add to your project's .claude/settings.json or global ~/.claude/settings.json:

{
  "mcpServers": {
    "aws-architecture-scanner": {
      "command": "python3",
      "args": ["/Users/youruser/.mcp-servers/aws-architecture-scanner/server.py"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

MCP Tools

1. scan_aws_architecture

Scans AWS environment and returns JSON data structure of all discovered resources.

Parameters:

• region (string, optional): AWS region to scan (default: us-east-1)
• vpc_id (string, optional): Specific VPC ID to scan (scans all VPCs if not provided)

Returns: JSON object containing:

• VPCs with subnets, gateways, route tables, security groups
• Compute resources (EC2, ECS, EKS, Lambda)
• Storage resources (S3, RDS, EFS, EBS)

Example:

scan_aws_architecture(region="us-east-1", vpc_id="vpc-06129df33ed494bbe")

2. generate_architecture_diagram

Scans AWS environment and generates a visual architecture diagram.

Parameters:

• region (string, optional): AWS region to scan (default: us-east-1)
• vpc_id (string, optional): Specific VPC ID to diagram
• output_path (string, required): Directory path to save the diagram
• filename (string, optional): Output filename without extension (default: "aws_architecture")
• format (string, optional): Output format - "png" or "svg" (default: "png")

Returns: Success message with output file path

Example:

generate_architecture_diagram(
    region="us-east-1",
    vpc_id="vpc-06129df33ed494bbe",
    output_path="/Users/youruser/Documents/diagrams",
    filename="my_vpc_architecture",
    format="png"
)

Usage Examples

Example 1: Scan your current VPC

# In Claude Code, use the MCP tool:
scan_aws_architecture(
    region="us-east-1",
    vpc_id="vpc-06129df33ed494bbe"
)

Example 2: Generate diagram for your VPC

generate_architecture_diagram(
    region="us-east-1",
    vpc_id="vpc-06129df33ed494bbe",
    output_path="/Users/youruser/Documents/Base/DevOps-ClaudeAi/test-cases/SM1/my-first-vpc",
    filename="my_first_vpc_diagram",
    format="png"
)

Example 3: Scan all VPCs in a region

scan_aws_architecture(region="us-west-2")

Output

Scan Output (JSON)

{
  "region": "us-east-1",
  "scan_time": "2026-04-17T18:45:00",
  "vpcs": [
    {
      "id": "vpc-06129df33ed494bbe",
      "cidr": "10.0.0.0/16",
      "name": "my-first-vpc",
      "subnets": [...],
      "internet_gateways": [...],
      "nat_gateways": [...],
      "route_tables": [...],
      "security_groups": [...]
    }
  ],
  "compute": {
    "ec2": [...],
    "ecs": [...],
    "eks": [...],
    "lambda": [...]
  },
  "storage": {
    "s3": [...],
    "rds": [...],
    "efs": [...],
    "ebs": [...]
  }
}

Diagram Output

• Professional PNG or SVG file
• Shows VPC boundaries with CIDR blocks
• Groups subnets by availability zone
• Displays connectivity between resources
• Uses official AWS service icons
• Clean, hierarchical layout

IAM Permissions Required

The AWS credentials must have read permissions for:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeInternetGateways",
        "ec2:DescribeNatGateways",
        "ec2:DescribeRouteTables",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeInstances",
        "ec2:DescribeVolumes",
        "ecs:ListClusters",
        "ecs:DescribeClusters",
        "eks:ListClusters",
        "eks:DescribeCluster",
        "lambda:ListFunctions",
        "s3:ListAllMyBuckets",
        "s3:GetBucketLocation",
        "rds:DescribeDBInstances",
        "elasticfilesystem:DescribeFileSystems",
        "elasticfilesystem:DescribeMountTargets"
      ],
      "Resource": "*"
    }
  ]
}

Troubleshooting

Issue: "diagrams library not installed"

Solution:

pip3 install diagrams graphviz
brew install graphviz  # macOS

Issue: "No module named 'graphviz'"

Solution: Install Graphviz system package (not just Python library)

brew install graphviz  # macOS
sudo apt-get install graphviz  # Linux

Issue: "Unable to assume role" or permission errors

Solution: Check AWS credentials and IAM permissions:

aws sts get-caller-identity
aws iam get-user

Issue: Diagram shows only some resources

Solution: Check that resources are in the correct region and VPC. Use vpc_id parameter to filter specific VPC.

Issue: S3 buckets not appearing

Solution: S3 buckets are region-filtered. Only buckets in the specified region will appear.

Advanced Usage

Scan multiple regions

for region in ["us-east-1", "us-west-2", "eu-west-1"]:
    scan_aws_architecture(region=region)

Generate diagrams for all VPCs

# First scan to get VPC IDs
scan_result = scan_aws_architecture(region="us-east-1")

# Parse JSON and generate diagram for each VPC
for vpc in scan_result["vpcs"]:
    generate_architecture_diagram(
        region="us-east-1",
        vpc_id=vpc["id"],
        output_path="/path/to/output",
        filename=f"vpc_{vpc['name']}",
        format="png"
    )

Limitations

• Single region per scan: Scans one region at a time (not multi-region by default)
• Diagram complexity: Very large environments (50+ resources) may produce cluttered diagrams
• S3 bucket limit: Shows maximum 5 S3 buckets per diagram for readability
• No cross-region connections: Does not show VPC peering or Transit Gateway connections
• Read-only: Only scans existing resources, does not create or modify AWS infrastructure

Future Enhancements

Potential features for future versions:

• Multi-region scanning with consolidated diagrams
• VPC peering and Transit Gateway visualization
• Security group rule visualization with port/protocol details
• Cost estimation for visualized resources
• Export to other formats (Terraform, CloudFormation)
• Mermaid diagram format for markdown documentation
• Interactive HTML diagrams
• Change detection (compare scans over time)

Contributing

This MCP server is part of your local development environment. Modify server.py to add features or fix issues.

License

For personal use in your AWS environment.