AWS Architecture Diagram MCP

An MCP server that turns a list of AWS services and connections into a self-contained, interactive architecture diagram — a single HTML file you can open in any browser or attach to an email. No server, no internet, no build step for the consumer.

It also generates .drawio files and exports the diagram's elements as neutral JSON — a machine-readable handoff (sidecar .json + export_diagram_json) that downstream apps consume: the official AWS IaC MCP for infrastructure, or a cost app such as aws-cost-app-mcp (a separate MCP) to price it. This server draws the diagram; it does not price or deploy.

Guided walkthrough — step through the architecture beat by beat, with the camera framing each stage and an overlay card explaining the WHY:

The same self-contained HTML is fully interactive — switch language, collapse containers, and flip the theme, all offline:

| Language switch (any language) | Collapsible containers | Light / dark theme | |:---:|:---:|:---:| | | | |

Disclaimer: Provided for illustration and documentation purposes, "as is" without warranty. The diagrams and any IaC or pricing it helps produce are starting points — review, test, and harden them (security, cost, and Well-Architected best practices) before using anything in production.

Features

• Interactive HTML diagram (React Flow) — draggable nodes, animated edges, dark/light theme, any-language switch, LR/TB layout. Fully self-contained (icons inlined as base64), so it works from file:// and as an email attachment.
• Guided walkthrough — define ordered beats; arrow keys or the dock's play button step through them. Each beat shows an overlay card (title, rich-markdown body, bullets, status chips, code snippets) whose position you pick per beat via cardSide (right default, left, top, or full centered modal), and tints — and optionally zooms (stepZoom) or isolates (stepFocus) — a subset of the diagram. Effects are opt-in per diagram, so a single HTML file both is the diagram and narrates it. See Guided walkthrough for all knobs.
• Any language — pass languages: ['en','ja','fr', …] and author any text field as a { en, ja, … } map; the toolbar shows a language dropdown and the whole diagram (labels, roles, walkthrough) re-renders in place. Not limited to EN/PT — localize the UI chrome for any language with uiStrings + langLabels.
• Multi-tab documents — pass sequence (or an explicit tabs[]) and the same single HTML file becomes a small document with a tab rail: the architecture canvas, the animated UML sequence player (the same renderer as the standalone render_diagram_media sequence output — play/step/keyboard, activation bars, alt/opt/loop/par fragments, participant groups, notes, tone/badge narration cards with source proof links, PNG/SVG export), and free-form doc tabs (sections, bullets, code), and typed tabs — any of 15 typed diagrams (Gantt, ER, swimlane, timeline, Kanban, journey, Wardley, decision workflow, …). Tabs deep-link via the URL hash. See Multi-tab documents.
• Collapsible containers — every group header has a fold toggle; collapse a VPC or account to a small box and the layout re-flows (start dense diagrams pre-collapsed with defaultCollapsed).
• Typed connections — mark edges as network / iam / event / data; each renders with a distinct color and dash style. Nodes carry a role describing what they do (shown on click).
• Auto icon resolution — 350+ AWS services mapped to official icons; the agent just passes a service name ("Amazon RDS"), no icon path needed.
• .drawio output — auto_generate_diagram writes a fully laid-out, editable .drawio file (native AWS4 shapes) using the same ELK compound engine as the HTML, so it supports arbitrary group nesting and typed connections too; export_diagram converts it to PNG/SVG/PDF (needs the drawio CLI).
• IaC handoff — exports a structured spec + instruction so an agent can generate production IaC via the official AWS IaC MCP (no re-implementation).
• Elements JSON handoff — every generated diagram writes a sidecar .json next to the HTML, and export_diagram_json extracts the same neutral payload (title, services[], connections[], groups[], per-node config) from an existing file. This is the contract a downstream cost app (e.g. aws-cost-app-mcp) or inventory/docs tool consumes. This server makes no pricing calls itself.

AWS diagram guidelines

The output follows the official AWS architecture diagram guidance: official icon set only, every node labeled, left-to-right / top-to-bottom flow, and an editable source (.drawio). Process narration is kept off the canvas — it lives in the guided-walkthrough overlay cards, not as clutter on the diagram. For best results, label nodes with the canonical service name from the AWS Architecture Icons set on first use, and re-download the icon set when AWS refreshes it (quarterly).

Prerequisites

• Node.js 18+
• The AWS Architecture Icons (downloaded separately — see below). They are not bundled due to their Terms of Use.

Setup

git clone <this-repo>
cd sample-architecture-diagram-mcp-server
npm install

# Icons, once per MACHINE. Fetch the current package straight from AWS:
./scripts/fetch-icons.sh --latest
# ...or download Icon-package_<date>.zip from
# https://aws.amazon.com/architecture/icons/ (leave it in ~/Downloads), then:
./scripts/fetch-icons.sh

With no argument the script picks up the newest Icon-package*.zip (or an older Asset-Package*.zip) in ~/Downloads (or ~/Desktop, or the current directory); --latest downloads it from aws.amazon.com instead. Re-running with a newer package overwrites the official icons, so the cache never goes stale. It installs ~810 official icons (services + group containers) into ~/.aws-architecture-icons — a shared cache that every copy of this server reads, so a plugin install, an npx run and a clone all see the same icons and reinstalling never means downloading the zip again. Pass --dest assets to fill this checkout instead.

Or let the agent do it: ask it to run the setup_icons tool — same script, no shell, and it reports the download link back if it can't find a zip.

Lookup order is: AWS_DIAGRAM_ICON_ROOT → this package's assets/ (if populated) → ~/.aws-architecture-icons. An icon root holds icons/ plus, optionally, aws-icons/ and tech-icons/ for your own SVGs.

Without icons the diagrams still render — nodes fall back to a category-colored initial, and every render tool says so in its result.

Register the MCP server

Clone this repo, run npm install, then point your MCP client at mcp-server.js with an absolute path:

{
  "mcpServers": {
    "aws-architecture-diagram": {
      "command": "node",
      "args": ["/absolute/path/to/sample-architecture-diagram-mcp-server/mcp-server.js"]
    }
  }
}

Icons are not bundled (AWS Terms of Use). On first run without them, diagrams render category-colored initials; add them with ./scripts/fetch-icons.sh (or the setup_icons tool) after downloading the Asset Package from https://aws.amazon.com/architecture/icons/. They install to the shared ~/.aws-architecture-icons, so this is a one-time, per-machine step.

As a Claude Code plugin

This repo is also a Claude Code plugin: it ships .claude-plugin/plugin.json, the .mcp.json above (resolved via ${CLAUDE_PLUGIN_ROOT}, so no absolute path to edit), and skills/aws-architecture-diagram/ — a skill that teaches the agent when to reach for an architecture view versus a sequence, a walkthrough or a delta, and the authoring rules that make the output look right.

The repo doubles as its own single-plugin marketplace (.claude-plugin/marketplace.json), so it installs in two commands:

/plugin marketplace add aws-samples/sample-architecture-diagram-mcp-server
/plugin install aws-architecture-diagram@aws-architecture-diagram

Installing a plugin clones the repo; it does not install dependencies. Run npm install in the installed plugin directory before the server will start. Icons need no extra step per install — the plugin reads the shared ~/.aws-architecture-icons cache, and if it is empty just ask the agent to run setup_icons. Other MCP clients can read skills/aws-architecture-diagram/SKILL.md as plain guidance.

Tools

| Tool | Purpose | |------|---------| | generate_html_diagram | Interactive self-contained HTML diagram in one call (the main one) | | diagram_create | Start an incremental draft; returns a draftId | | diagram_add_services | Append services (nodes) to a draft | | diagram_add_connections | Append connections (edges) to a draft | | diagram_add_groups | Append container groups to a draft | | diagram_add_steps | Append guided-walkthrough beats to a draft | | diagram_add_sequence | Add an animated UML sequence diagram as a second tab of a draft | | diagram_add_doc_tab | Add a prose tab (sections / bullets / code) to a draft | | diagram_render | Render an incremental draft to a self-contained HTML file | | validate_diagram | Lint a diagram payload before rendering: unresolved icons, dangling connection endpoints, orphaned parentId/step references | | diagram_delta | Diff two diagram JSONs into a Before/Delta/After payload | | generate_sequence_diagram | Standalone animated UML sequence player (no architecture canvas) | | sequence_create | Start an incremental sequence draft; returns a draftId | | sequence_add_participants | Append lifelines to a sequence draft | | sequence_add_messages | Append messages (arrows) to a sequence draft | | sequence_add_notes | Append notes to a sequence draft | | sequence_add_fragments | Append combined fragments (alt / opt / loop / …) anchored by event id | | sequence_add_groups | Append participant groups (bands) to a sequence draft | | sequence_render | Render a sequence draft to a self-contained HTML file | | render_diagram_media | Screenshot/record a generated HTML diagram to PNG, animated GIF or animated SVG | | auto_generate_diagram | Fully auto-laid-out .drawio file | | generate_diagram | .drawio with manual x/y positioning | | export_diagram | Convert .drawio → PNG/SVG/PDF (needs drawio CLI) | | resolve_icon | Resolve a service name to its icon filename (or list all) | | setup_icons | Install the AWS Architecture Icons into the shared per-machine cache (auto-detects the Asset Package zip in ~/Downloads) | | list_shapes | AWS4 drawio shape names (for the .drawio path) | | list_service_configs | IaC config fields per service | | export_iac_json | Extract an AWS IaC MCP handoff payload (resources + dependencies) from a diagram | | export_diagram_json | Extract the diagram's elements as neutral JSON (title, services, connections, groups) for downstream apps |

For a diagram built up in stages (e.g. as an agent reasons through an architecture), use the incremental builder: diagram_create → diagram_add_* (in any order) → diagram_render. For a single-shot build, use generate_html_diagram. Both speak the exact same service/connection/group/step shape.

Example: generate_html_diagram

{
  "title": "My App",
  "subtitle": "Serverless API",
  "outputPath": "/tmp/my-app.html",
  // Optional header band above the canvas, for a file