Diagram AI Generator 🚀

Professional AI-powered architecture diagram generator with multi-cloud support and MCP (Model Context Protocol) server integration. Generate beautiful, accurate diagrams with provider-specific icons for AWS, Azure, GCP, Kubernetes, and more.

✨ Features

• 🎯 Professional Diagrams: Generate diagrams with real provider icons (AWS Lambda, Azure Functions, GCP Storage, etc.)

• 🌐 Multi-Cloud Support: Mix AWS, Azure, GCP, and other providers in a single diagram

• 🧠 Smart Node Suggestions: Automatic suggestions when component names don't match exactly

• 🔧 MCP Server Integration: Works seamlessly with Claude Desktop and other MCP clients

• 🐳 Docker Ready: One-command deployment with Docker Compose

• 📦 PyPI Package: Install easily with pip

• 🏗️ Modular Architecture: Clean, scalable, and maintainable codebase

📸 Example Output

Here's a real diagram generated with a simple text prompt:

Prompt: "aplicación web en AWS con ALB, EC2 en múltiples zonas de disponibilidad, RDS con réplica de lectura, ElastiCache para caché y CloudFront para CDN y muchas mas cosas con layout horizontal para que se vea completo y bien"

Generated in seconds with professional AWS icons, proper layout, and accurate cloud architecture patterns! 🎉

⚡ How It Works

Simply describe your architecture in plain text:

• ✅ "Create a microservices architecture with load balancer, containers, and Redis cache"

• ✅ "Design a data pipeline with S3, Lambda, and Kinesis"

• ✅ "Build a multi-region setup with CloudFront, ALB, and RDS"

The AI understands your requirements and generates production-ready diagrams with the correct cloud provider icons and relationships.

🚀 Quick Start

Step 1: Install the package

pip install diagram-ai-generator

Note: Use your system Python (the one Claude Desktop uses):

# macOS
/usr/local/bin/python3 -m pip install diagram-ai-generator

# Or force install from PyPI
pip install diagram-ai-generator

Step 2: Configure Claude Desktop

That's it! Now configure it in Claude Desktop (see next section).

🔌 Claude Desktop Configuration

Edit your claude_desktop_config.json:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Basic Configuration:

{
    "mcpServers": {
        "diagram-ai-generator": {
            "command": "python3",
            "args": ["-m", "src.application.mcp.server_modular"]
        }
    }
}

With Custom Output Directory (Optional):

{
    "mcpServers": {
        "diagram-ai-generator": {
            "command": "python3",
            "args": ["-m", "src.application.mcp.server_modular"],
            "env": {
                "DIAGRAM_OUTPUT_DIR": "/Users/yourname/diagrams"
            }
        }
    }
}

The output directory will be created automatically if it doesn't exist. If not specified, diagrams are saved to ./generated_diagrams/ in your current directory.

After configuration:

1. Restart Claude Desktop

2. Start using it! Ask Claude to create architecture diagrams

🛠️ Usage

MCP Server Integration

The MCP server provides 5 professional tools for creating diagrams:

1. step1_list_providers - List all available providers (AWS, Azure, GCP, etc.)

2. step2_get_categories - Get categories for a specific provider

3. step3_get_nodes - Get exact node names for a category

4. create_diagram_from_json - Generate diagrams from JSON specifications

5. multicloud_helper - Guide for multi-cloud diagrams

Recommended Workflow

1. step1_list_providers()
   ↓
2. step2_get_categories("aws")
   ↓  
3. step3_get_nodes("aws", "compute")
   ↓
4. create_diagram_from_json(spec)

💡 Real-World Examples

Example 1: AWS Serverless E-commerce

Simple prompt: "Create a serverless e-commerce backend on AWS with API Gateway, Lambda functions, DynamoDB, and S3 for product images"

What you get:

• Professional AWS architecture diagram

• Correct service icons and relationships

• Production-ready layout

Example 2: Multi-Cloud Disaster Recovery

Simple prompt: "Multi-cloud setup with primary services in AWS and failover in Azure"

What you get:

• Clear separation between cloud providers

• Cross-cloud connections

• Both AWS and Azure specific icons

Example 3: Kubernetes Microservices

Simple prompt: "Kubernetes cluster with microservices, ingress controller, and persistent storage"

What you get:

• Kubernetes-specific resources

• Proper namespace organization

• Service mesh visualization

Example: Single-Cloud Diagram

{
  "title": "AWS Serverless Architecture",
  "provider": "aws",
  "layout": "horizontal",
  "components": [
    {
      "id": "api_gateway",
      "type": "APIGateway",
      "category": "network",
      "label": "API Gateway"
    },
    {
      "id": "lambda",
      "type": "Lambda",
      "category": "compute", 
      "label": "Lambda Function"
    },
    {
      "id": "dynamodb",
      "type": "Dynamodb",
      "category": "database",
      "label": "DynamoDB"
    }
  ],
  "connections": [
    {
      "from": "api_gateway",
      "to": "lambda",
      "color": "darkgreen",
      "style": "bold",
      "label": "HTTP"
    }
  ]
}

Example: Multi-Cloud Diagram with Specific Icons

{
  "title": "Multi-Cloud Architecture",
  "provider": "generic",
  "layout": "horizontal", 
  "components": [
    {
      "id": "aws_lambda",
      "type": "Lambda",
      "category": "compute",
      "component_provider": "aws",
      "label": "AWS Lambda"
    },
    {
      "id": "azure_func",
      "type": "FunctionApps", 
      "category": "compute",
      "component_provider": "azure",
      "label": "Azure Functions"
    },
    {
      "id": "gcp_func",
      "type": "Functions",
      "category": "compute",
      "component_provider": "gcp", 
      "label": "GCP Functions"
    }
  ],
  "clusters": [
    {
      "name": "AWS Cloud",
      "components": ["aws_lambda"]
    },
    {
      "name": "Azure Cloud",
      "components": ["azure_func"] 
    },
    {
      "name": "GCP Cloud",
      "components": ["gcp_func"]
    }
  ]
}

🌐 Multi-Cloud Support

Key Features:

• ✅ Real Provider Icons: Each component uses its actual provider icon

• ✅ Mixed Architectures: Combine AWS, Azure, GCP in one diagram

• ✅ Smart Clustering: Automatic grouping by cloud provider

• ✅ Cross-Cloud Connections: Show inter-cloud communication

Important Notes:

• Use "provider": "generic" for multi-cloud diagrams

• Add "component_provider": "aws" to each component

• Use exact node names from step3_get_nodes()

⚙️ Configuration Options

Output Directory

By default, diagrams are saved to ./generated_diagrams/. You can customize this:

{
    "mcpServers": {
        "diagram-ai-generator": {
            "command": "python3",
            "args": ["-m", "src.application.mcp.server_modular"],
            "env": {
                "DIAGRAM_OUTPUT_DIR": "/path/to/your/diagrams"
            }
        }
    }
}

The directory will be created automatically if it doesn't exist.

🧠 Smart Features

Automatic Node Suggestions

When you use incorrect node names, the system suggests alternatives:

⚠️  NODO NO ENCONTRADO: 'DynamoDB' en aws/database
💡 SUGERENCIAS: Dynamodb, DocumentdbMongodbCompatibility
✅ USANDO SUGERENCIA: 'Dynamodb' en lugar de 'DynamoDB'

Common Name Corrections

• ❌ DynamoDB → ✅ Dynamodb

• ❌ EventBridge → ✅ Eventbridge

• ❌ S3 → ✅ SimpleStorageServiceS3

• ❌ PubSub → ✅ Pubsub

📋 Supported Providers

• AWS - 400+ services across 30+ categories

• Azure - 300+ services across 25+ categories

• GCP - 200+ services across 15+ categories

• Kubernetes - 50+ resources across 10+ categories

• OnPrem - 200+ tools and services

• And 14 more providers...

🔍 Troubleshooting

Common Issues

1. Module not found error Make sure you have Python 3.10+ and installed in the correct Python:

# Check Python version
python3 --version  # Should be 3.10 or higher

# Install
/usr/local/bin/python3 -m pip install diagram-ai-generator

2. Graphviz not found

# macOS  
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

3. Custom output directory not working

• Make sure the path exists or the directory is writable

• Use absolute paths in the configuration

• Check Claude Desktop logs for errors

🔧 Development

Contributing

1. Fork the repository

2. Create a feature branch from develop

3. Make your changes

4. Open a PR to develop

Release Process

Automated with GitHub Actions:

1. PR to master: Triggers checks

   • Tests and build validation

   • Analyzes changes (code vs docs only)

   • Comments on PR if release will be created

2. Merge to master: Auto-deploys if version changed

   • Builds package

   • Publishes to PyPI

   • Creates GitHub release

   • Updates CHANGELOG

Versioning

Follow Conventional Commits:

• feat: - New feature (bumps MINOR version)

• fix: - Bug fix (bumps PATCH version)

• BREAKING CHANGE: - Breaking change (bumps MAJOR version)

• docs: - Documentation only (no release)

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• 🐛 Issues: GitHub Issues

• 📝 Changelog: CHANGELOG.md

Made by Carlos Martínez García-Villarrubia