Cloud Architect MCP

An MCP server that helps design AWS cloud architectures. Use it from Cursor, VS Code, Claude Desktop, or any MCP-compatible client to generate architecture designs, cost estimates, and Terraform code.

Supported LLM providers: Google Gemini, OpenAI (GPT), Anthropic (Claude)

Tools

| Tool | Description | Input | |------|-------------|-------| | generate_architecture | Design an AWS architecture (services, networking, components) | projectDescription | | estimate_cost | Estimate monthly AWS costs for an architecture | architecture | | generate_terraform | Generate Terraform (HCL) for an architecture | architecture |

Typical workflow

generate_architecture  →  estimate_cost  →  generate_terraform

Prerequisites

• Node.js 18+
• API key for at least one provider:
  • Google Gemini
  • OpenAI
  • Anthropic

Installation

npm package (recommended)

npm install cloud-architect-mcp

Or run without installing:

npx cloud-architect-mcp

Add to your package.json:

{
  "dependencies": {
    "cloud-architect-mcp": "^1.2.0"
  }
}

From source

git clone <repo-url>
cd cloud-architect-mcp
npm install
npm run build

LLM provider configuration

Copy the example env file and add your API key:

cp .env.example .env

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | LLM_PROVIDER | No | gemini, openai, or anthropic. Auto-detects if omitted. | | GEMINI_API_KEY | If using Gemini | Google AI Studio API key | | GEMINI_MODEL | No | Default: gemini-2.0-flash | | OPENAI_API_KEY | If using GPT | OpenAI API key | | OPENAI_MODEL | No | Default: gpt-4o-mini | | ANTHROPIC_API_KEY | If using Claude | Anthropic API key | | ANTHROPIC_MODEL | No | Default: claude-3-5-haiku-20241022 |

Examples

Use Gemini (default):

LLM_PROVIDER=gemini
GEMINI_API_KEY=your-gemini-key

Use OpenAI GPT:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

Use Anthropic Claude:

LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514

If LLM_PROVIDER is not set, the server picks the first available key in order: Gemini → OpenAI → Anthropic. Set LLM_PROVIDER explicitly when you have multiple keys.

IDE setup

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "cloud-architect": {
      "command": "npx",
      "args": ["-y", "cloud-architect-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

See examples/cursor.mcp.json.

VS Code

Requires GitHub Copilot with MCP support (VS Code 1.102+).

Create .vscode/mcp.json in your project:

{
  "servers": {
    "cloud-architect": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cloud-architect-mcp"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Note: VS Code uses "servers" (not "mcpServers" like Cursor).

User-level config: run MCP: Open User Configuration from the Command Palette.

Sandbox (macOS/Linux): if sandboxing is enabled, allow LLM API domains:

{
  "servers": {
    "cloud-architect": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cloud-architect-mcp"],
      "envFile": "${workspaceFolder}/.env",
      "sandboxEnabled": true
    }
  },
  "sandbox": {
    "network": {
      "allowedDomains": [
        "generativelanguage.googleapis.com",
        "api.openai.com",
        "api.anthropic.com"
      ]
    }
  }
}

See examples/vscode.mcp.json.

Claude Desktop

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "cloud-architect": {
      "command": "npx",
      "args": ["-y", "cloud-architect-mcp"],
      "env": {
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "your-key-here"
      }
    }
  }
}

See examples/claude-desktop.mcp.json.

Local install (any IDE)

{
  "command": "node",
  "args": ["./node_modules/cloud-architect-mcp/index.js"],
  "envFile": "${workspaceFolder}/.env"
}

Restart your IDE after changing MCP config.

Usage

In Agent mode (Cursor / VS Code Copilot) or Claude Desktop chat, ask naturally:

Use cloud-architect to design AWS architecture for a multi-tenant SaaS
with 100k users, Node.js, PostgreSQL, Redis, and high availability.

Use estimate_cost for this architecture: [paste architecture]

Use generate_terraform for this architecture: [paste architecture]

Scripts

| Command | Description | |---------|-------------| | npm run dev | Run with tsx (no build) | | npm run build | Compile TypeScript to dist/ | | npm start | Run MCP server |

Project structure

cloud-architect-mcp/
├── src/
│   ├── index.ts
│   ├── services/
│   │   ├── llm.config.ts      # Provider & model config
│   │   └── llm.service.ts      # Gemini, OpenAI, Anthropic
│   └── tools/
├── .vscode/mcp.json            # VS Code example config
├── examples/                   # MCP configs for Cursor, VS Code, Claude
├── .env.example
└── index.js                    # CLI entry (cloud-architect-mcp)

Troubleshooting

No LLM API key found

Set at least one of GEMINI_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY in .env or MCP env.

Wrong provider being used

Set LLM_PROVIDER explicitly when multiple API keys are present.

MCP server not appearing

1. Restart IDE fully
2. Check MCP config syntax (Cursor: mcpServers, VS Code: servers)
3. Run npm run build if using local source

429 / quota errors

Enable billing for your provider or switch LLM_PROVIDER to another model with available quota.

License

MIT