Cloud Architecture MCP Server

An MCP (Model Context Protocol) server for cloud architecture work — generates draw.io and Excalidraw diagrams, reviews solution documents against guardrails (with severity-weighted scoring and framework references), runs structural gap analysis, estimates costs, generates Terraform skeletons, and manages reusable architectural patterns for AWS, GCP, and Azure.

Source: github.com/chrishorne74/cloud-architecture-mcp

Tools

Diagram Generation

Tool	Description
`generate_diagram`	Generate draw.io XML for any AWS / GCP / Azure architecture using native cloud service icons
`generate_excalidraw_diagram`	Generate an Excalidraw elements JSON for the same architecture — pass to the Excalidraw MCP's `create_view` or `export_to_excalidraw`
`list_shapes`	Browse all available native service icon IDs per provider (aws, gcp, azure) and optional category
`get_diagram_for_pattern`	Render a stored pattern as a draw.io diagram
`get_excalidraw_for_pattern`	Render a stored pattern as an Excalidraw diagram
`validate_diagram`	Pre-flight check before generating — catches duplicate IDs, broken edge references, self-loops, orphaned nodes, invalid group assignments, and unknown service IDs (with "did you mean" suggestions)
`estimate_complexity`	Complexity rating (🟢 Low / 🟡 Medium / 🔴 High) with metrics: service diversity, redundancy, cross-zone connections, async edges

Architecture Analysis

Tool	Description
`suggest_improvements`	Structural gap analysis against the loaded guardrails — detects missing WAF on public endpoints, single-instance databases, missing secrets management, direct internet-to-compute paths, unauthenticated public APIs, AI services with direct data store access, and more
`estimate_cost`	Indicative monthly cost breakdown: bill of materials with cost band ($/$$/$$$), typical range, and pricing model per component, highlighting big-ticket items
`generate_terraform`	Terraform skeleton (HCL) from a pattern or inline architecture — resource stubs with TODO-annotated arguments and guardrail hints (Multi-AZ, encryption, tagging) baked in

Architectural Patterns

Tool	Description
`list_architectural_patterns`	List stored patterns with metadata, filterable by provider and category
`search_patterns`	Full-text relevance search across pattern names, descriptions, tags, when-to-use text, and component services
`get_pattern`	Get full details of a stored pattern including all nodes, edges, tradeoffs, and when-to-use guidance
`save_architectural_pattern`	Save a new custom pattern for future reuse
`clone_pattern`	Copy an existing pattern under a new ID — useful for creating provider variants of built-in patterns
`validate_pattern`	Validate a pattern (stored or raw JSON) against the schema: structural checks, unknown service IDs with suggestions, stale guardrail references, schema version
`delete_pattern`	Permanently delete a stored pattern (requires `confirm: true`)
`generate_architecture_document`	Generate a structured Markdown architecture document: component table, NFR table (RTO/RPO/cost/scaling), data flow, failure modes, tradeoffs, and guardrail coverage

Guardrails

Tool	Description
`list_guardrails`	View all architecture standards with severities and framework references (AWS Well-Architected, CIS, NIST, OWASP, FinOps)
`review_architecture`	Start a compliance review — returns an evaluation rubric so the AI assesses each rule semantically (understanding negation, synonyms, and applicability) rather than by keyword matching
`format_review_report`	Second step of the review — takes per-rule verdicts (PASSED / FAILED / WARNING / NOT_APPLICABLE) and produces a severity-weighted scored report; any failed CRITICAL rule caps the score at 49
`reload_guardrails`	Reload the guardrails file after editing without restarting the server

Resources

guardrails://current — Raw guardrails Markdown
patterns://catalog — All stored patterns as JSON

Setup

Option A — Claude Desktop Extension (.mcpb)

Download dist/cloud-architecture.mcpb from the releases page and install it directly in Claude Desktop. No configuration required — the bundle includes all compiled code, patterns, and guardrails.

To use custom guardrails or patterns, set the optional user config fields in Claude Desktop's extension settings:

Custom Guardrails File — path to your own guardrails.md
Custom Patterns Directory — path to a folder of pattern JSON files

Option B — Manual Configuration

1. Install & Build

git clone https://github.com/chrishorne74/cloud-architecture-mcp
cd cloud-architecture-mcp
npm install
npm run build

2. Add to Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cloud-architecture": {
      "command": "node",
      "args": ["C:\\path\\to\\cloud-architecture-mcp\\build\\index.js"],
      "env": {
        "GUARDRAILS_FILE": "C:\\path\\to\\cloud-architecture-mcp\\guardrails.md",
        "PATTERNS_DIR": "C:\\path\\to\\cloud-architecture-mcp\\patterns"
      }
    }
  }
}

Draw.io Integration

This server generates draw.io XML. To render diagrams, also configure the draw.io MCP server. When Claude calls generate_diagram, it returns XML that can be passed directly to open_drawio_xml.

Excalidraw Integration

When Claude calls generate_excalidraw_diagram, it returns a JSON elements array. Pass this to:

create_view — renders live in the chat
export_to_excalidraw — uploads and returns a shareable URL

Usage Examples

Generate a diagram

"Create an AWS three-tier web architecture with an ALB, Auto Scaling Group, RDS Multi-AZ, and ElastiCache"

Claude calls generate_diagram → passes XML to open_drawio_xml to render.

Validate before generating

"Validate this architecture spec before I generate it"

Claude calls validate_diagram to surface any issues (orphaned nodes, bad references) before spending time on layout.

Search patterns

"Find patterns related to high availability and failover"

Claude calls search_patterns with "high availability failover" and returns ranked matches.

Document a pattern

"Generate an architecture document for the serverless-api pattern"

Claude calls generate_architecture_document → produces a Markdown doc with component table, data flow, failure modes, and tradeoffs.

Assess complexity

"How complex is this architecture and what should I watch out for?"

Claude calls estimate_complexity → returns Low/Medium/High with metrics and specific observations about redundancy, async edges, and cross-zone routing.

Clone and customise a pattern

"Clone the three-tier-web pattern but make it Azure"

Claude calls clone_pattern with provider_override: "azure" → creates a copy you can then modify.

Review against guardrails

"Review this architecture document against our guardrails: [paste document]"

Claude calls review_architecture → assesses each rule semantically → calls format_review_report → returns a severity-weighted compliance report with evidence per rule.

Find structural gaps

"What's missing from this architecture?"

Claude calls suggest_improvements → reports guardrail-mandated components that are absent (no WAF, single-instance database, no secrets manager…) with guardrail IDs and severities.

Estimate cost and generate IaC

"What will the serverless-api pattern roughly cost, and give me a Terraform starting point"

Claude calls estimate_cost → bill of materials with cost bands; then generate_terraform → HCL resource stubs with guardrail hints.

Bundled Patterns (26)

Patterns carry v2 metadata where applicable: RTO / RPO, cost tier, scaling behaviour, and Well-Architected pillar mapping.

AWS Patterns

ID	Name	Description
`three-tier-web`	Three-Tier Web Application	Classic web / app / data tier on AWS
`serverless-api`	Serverless REST API	API Gateway + Lambda + DynamoDB
`microservices-ecs`	Microservices on ECS Fargate	Multiple services behind an ALB on Fargate
`k8s-eks-aws`	Kubernetes on EKS	ALB ingress, multi-AZ node groups, Aurora, IRSA
`event-driven`	Event-Driven Architecture	EventBridge + SQS + Lambda fan-out
`rag-genai-aws`	RAG GenAI Application	Bedrock + OpenSearch vectors + ingestion pipeline
`saas-multi-tenant-aws`	Multi-Tenant SaaS	Pooled Fargate + Aurora RLS + tenant catalog + async onboarding
`batch-etl-aws`	Batch ETL Pipeline	EventBridge schedule + Step Functions + Glue + Athena
`data-lake`	Data Lake on AWS	S3 zones + Glue + Athena + QuickSight
`hub-spoke-network`	Hub-and-Spoke Network	Transit Gateway with shared services hub
`vm-single-aws`	Single EC2 Instance	Baseline single-AZ VM — development / internal
`vm-active-passive-aws`	EC2 Active / Passive	Warm standby with EIP reassignment failover
`vm-lb-2az-aws`	EC2 Load Balanced — 2 AZ	ALB + ASG across two availability zones
`vm-lb-3az-aws`	EC2 Load Balanced — 3 AZ	ALB + ASG across three availability zones
`vm-spot-hybrid-aws`	EC2 Spot + On-Demand Hybrid	Mixed instance ASG with Spot cost optimisation
`vm-warm-standby-aws`	EC2 Warm Standby DR	Route 53 failover with cross-region RDS replica
`vm-active-active-multiregion-aws`	EC2 Active-Active Multi-Region	Two-region active-active with Route 53 latency routing

GCP Patterns

ID	Name	Description
`k8s-gke-gcp`	Kubernetes on GKE	Global LB + Cloud Armor, regional cluster, Cloud SQL HA
`vm-single-gcp`	Single Compute Engine VM	Single-zone VM — development / internal
`vm-regional-mig-gcp`	Regional MIG	Regional Managed Instance Group across 3 zones

Azure Patterns

ID	Name	Description
`k8s-aks-azure`	Kubernetes on AKS	App Gateway WAF ingress, zone-spread pools, PostgreSQL HA
`vm-single-azure`	Single Azure VM	Single-zone VM — development / internal
`vm-availability-zones-azure`	Azure VM — Availability Zones	VMs pinned across 3 availability zones
`vm-vmss-azure`	Azure VM Scale Set	VMSS flexible orchestration across 3 zones

Multi-Cloud Patterns

ID	Name	Description
`cloud-pattern-single-provider-dr`	Single Provider with DR (Preferred)	Default topology — AZ-separated DR in one region
`cloud-pattern-multi-cloud-workload-selection`	Multi-Cloud Workload Selection	Best-of-breed: ML on GCP, EUC on Azure, general compute on AWS

Pattern Editor (Windows)

A standalone Windows pattern editor is included at editor/dist/pattern-editor.exe (57 MB, no install required).

Double-click to launch — auto-opens in your browser at http://localhost:3033
Reads and writes pattern JSON files from a patterns/ folder next to the .exe
Create, edit, and delete patterns with a visual form UI

To rebuild the exe:

cd editor
npm install
npm run build:exe

Customising Guardrails

Edit guardrails.md using this format:

## Category Name

- Rule description [CRITICAL] [ref: AWS-WA SEC08-BP02, NIST SC-28]
- Another rule [HIGH]
- Lower priority rule [MEDIUM]
- Informational note [LOW]

Severity tags: [CRITICAL] [HIGH] [MEDIUM] [LOW] (defaults to MEDIUM if omitted). Optional [ref: ...] tags map a rule to published frameworks (AWS/Azure Well-Architected, CIS, NIST, OWASP, FinOps, ISO 27001) and are shown in reviews and listings.

The bundled guardrails cover: Security, Resilience, Networking, Observability, Cost/FinOps, Compliance, Governance, Zero Trust, Supply Chain, AI Workloads (OWASP LLM Top 10-aligned), Sustainability, and approved Cloud Patterns — 86 rules in total.

Review scoring is severity-weighted: CRITICAL=10, HIGH=5, MEDIUM=2, LOW=1. PASSED earns full weight, WARNING half, FAILED zero; NOT_APPLICABLE rules are excluded. A failed CRITICAL rule caps the score at 49.

Call reload_guardrails to pick up changes without restarting the server.

Environment Variables

Variable	Default	Description
`GUARDRAILS_FILE`	`./guardrails.md`	Path to the guardrails Markdown file
`PATTERNS_DIR`	`./patterns/`	Directory containing pattern JSON files
`USER_GUARDRAILS_FILE`	(empty)	Override for `.mcpb` user config — takes precedence over `GUARDRAILS_FILE`
`USER_PATTERNS_DIR`	(empty)	Override for `.mcpb` user config — takes precedence over `PATTERNS_DIR`

Building the .mcpb Bundle

npm run build
node scripts/build-mcpb.js
# Output: dist/cloud-architecture.mcpb

The bundle is a ZIP archive containing compiled JS, patterns, guardrails, and production node_modules. It can be installed directly in Claude Desktop without any separate npm install.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/prompts		.github/prompts
editor		editor
patterns		patterns
scripts		scripts
src		src
.gitignore		.gitignore
README.md		README.md
guardrails.md		guardrails.md
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Cloud Architecture MCP Server

Tools

Diagram Generation

Architecture Analysis

Architectural Patterns

Guardrails

Resources

Setup

Option A — Claude Desktop Extension (.mcpb)

Option B — Manual Configuration

Draw.io Integration

Excalidraw Integration

Usage Examples

Generate a diagram

Validate before generating

Search patterns

Document a pattern

Assess complexity

Clone and customise a pattern

Review against guardrails

Find structural gaps

Estimate cost and generate IaC

Bundled Patterns (26)

AWS Patterns

GCP Patterns

Azure Patterns

Multi-Cloud Patterns

Pattern Editor (Windows)

Customising Guardrails

Environment Variables

Building the .mcpb Bundle

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages