archdiagram
Exports diagrams as .drawio files that can be opened and edited in draw.io / diagrams.net, with native vendor stencils, portable/embedded icons, and optionally draw.io's compressed raw-deflate model encoding so shapes and text remain editable after import.
Supports Kubernetes vendor icons as an architecture node family, so generated architecture specs can render Kubernetes resources and related service diagrams with the correct vendor iconography.
Renders diagrams to PDF (and embedded-icon draw.io/VSDX files) specifically tailored for import into Lucidchart, baking vendor icons in so they always render and preserving visual fidelity for handoff, printing, and editing inside Lucid.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
archdiagram
Turn a JSON spec into an editable diagram for four families: architecture, process flow, decision flow, and data flow. Architecture nodes can use Azure, AWS, GCP, and Kubernetes vendor icons. The other families use editable shapes, loops, labelled branches, lineage edges, and optional swim lanes.
A coding agent (Cursor, Claude Code, Codex) translates a natural-language architecture into a small JSON spec; the deterministic Python core renders that spec to:
Format | Best for | Vendor icons | Editable after import |
| Lucidchart visual fidelity, handoff, printing | baked in, always render | no (Lucid embeds as image) |
| editing in draw.io / diagrams.net | native stencils or embedded | yes |
| Visio / Lucid editable import | embedded PNG glyphs | yes |
| portable vector image | embedded icons | SVG shapes are editable in vector tools |
| standalone browser view | embedded icons | via embedded SVG |
| PowerPoint handoff | embedded PNG glyphs | shapes and text are editable |
drawio has native, portable, and compressed modes. Compressed mode uses
draw.io's raw-deflate model encoding and portable embedded icons. For Lucidchart,
prefer PDF when icon fidelity matters; compressed draw.io imports can lose image
shapes. PDF needs the optional Node helpers. Shape-only PPTX and VSDX need no Node.
Lucid note: Lucid does not map draw.io's named vendor stencils or its
img/lib/...icon references, so those render blank on import..drawio/.vsdxtherefore embed icons (--drawio-mode portable) to maximise render success, and the PDF is the reliable icons-always-render deliverable for Lucid.
Gallery
Rendered from the specs in examples/ - same engine, real vendor icons.
Azure | AWS | GCP |
|
|
|
Related MCP server: tech-icons
Design constraints
Core engine = pure Python stdlib. No graphviz, no browser, no third-party Python deps. Spec validation is hand-rolled (no
jsonschema)..vsdxis written withzipfile+xml.Python 3.11+. Tests use stdlib
unittest.Optional, isolated, non-stdlib deps:
mcpSDK - only insidemcp_server/.Node +
@resvg/resvg-js- rasterise SVG icons to PNG for.vsdx,.pptx, and.pdf. If absent,.vsdxand.pptxuse labelled fallback shapes;.pdferrors with an install hint.Node +
pdfkit+svg-to-pdfkit- SVG -> PDF for.pdf.
Vendor icons are not committed. Fetch them with
tools/download_icons.py.
Quick start
# 1. check the core; add --icons to fetch vendor icons
python -m tools.bootstrap
python -m tools.bootstrap --icons
# 2. (optional) install the Node rasterise/pdf bridge
python -m tools.bootstrap --pdf
# 3. render a spec
python -m archdiagram.cli render examples/sample_spec.json --format pdf -o out/arch.pdf
python -m archdiagram.cli render examples/sample_spec.json --format drawio -o out/arch.drawio --drawio-mode portable
python -m archdiagram.cli render examples/sample_spec.json --format vsdx -o out/arch.vsdx
python -m archdiagram.cli render examples/workflow_swimlane.json --format svg -o out/workflow.svg
python -m archdiagram.cli render examples/workflow_swimlane.json --format html -o out/workflow.html
python -m archdiagram.cli render examples/workflow_swimlane.json --format pptx -o out/workflow.pptxSpec format
{
"title": "Web platform",
"direction": "LR",
"groups": [{ "id": "app", "label": "Application tier", "vendor": "azure" }],
"nodes": [
{ "id": "web", "service": "azure.app_service", "label": "Web App", "group": "app" },
{ "id": "aks", "service": "azure.aks", "label": "AKS", "group": "app" },
{ "id": "kv", "service": "azure.key_vault", "label": "Key Vault" }
],
"edges": [
{ "source": "web", "target": "aks", "label": "http" },
{ "source": "aks", "target": "kv" }
]
}service accepts a canonical ID, alias, providerless name, or a confident fuzzy
match. Unknown names render a fallback box with suggestions. Add --strict to
validate or render to reject unresolved names.
Four families
Family | Primary nodes | Typical direction | Example |
Architecture |
|
| |
Process flow |
|
| |
Decision flow | decision diamonds and separate end nodes |
| |
Data flow |
|
|
Spec reference
Top level:
title,direction(LR,RL,TB,BT),nodes,edges, optionalgroups,lanes, andlane_orientation(horizontalorvertical).Node: unique string
id, exactly one ofserviceorshape, optionallabel,group,lane, nonnegative integertier, and explicitx/y. The shape enum isstart,end,process,decision,io,document,data_store.Edge:
sourceandtargetnode IDs, optionallabel,kind(flowordata),directed,dashed, and six digit RGBcolorwith optional#.Group:
id,label, and optionalvendor; a node'sgroupnames it.Lane: ordered
{id,label}objects; a node'slanenames one. Nodes without a lane appear in a trailing unassigned band. Explicitx/yare rejected in modern lane mode so a node cannot leave its band. Groups nested in lanes are outside the supported layout.
For older specs, kind remains accepted as a shape alias. Specs without new
shape or lane fields use the legacy layout and keep the checked in golden bytes.
Index a larger local icon pack
The bundled catalog covers common services. To search and render additional SVGs from a
vendor icon pack you already have, place them under icons/<vendor>/, with optional
category folders, then build a manifest:
python -m tools.build_catalog --icons icons --out catalog/manifest.json
python -m archdiagram.cli catalog search "AI Studio"The manifest records service IDs, categories, aliases, dimensions, and paths relative to
icons/. The SVG files remain local. Bundled IDs take precedence when both catalogs
contain the same service. Generated IDs use lowercase words joined by underscores,
such as azure.ai_studio; duplicate names gain _2, _3, and so on. The icon
directory used for rendering must be the same one used to build the manifest. For
nondefault locations, set ARCHDIAGRAM_CATALOG to the manifest path and pass
--icons <directory> when rendering (or set ARCHDIAGRAM_ICONS). Generated SVGs
are embedded in draw.io when no native stencil is available.
For older workflow specs, nodes[].kind still selects process, decision,
data, start, or end. New specs should use shape. edges[].kind: "data"
draws a dashed data transfer.
python -m archdiagram.cli templates list
python -m archdiagram.cli templates suggest "approval between two teams"
python -m archdiagram.cli templates show swimlane
python -m archdiagram.cli templates show dataflowLayout
Node positions use a deterministic layered layout. New shape specs use an
iterative cycle tolerant ranker: loop backs stay visible while downstream steps
remain on later ranks. Swim lanes reserve ordered bands. Explicit tier
overrides rank; x/y override placement outside modern lane mode.
Use from an AI agent
This repo is built to be driven by agentic AI tools (Cursor, Claude Code/Desktop, Codex, ...) straight from Git. Pick either path:
1. As a skill
Choose the relevant family skill under skill/. The old
skill/SKILL.md is a compatibility pointer. Each skill has
spec rules, a worked example, and a render and inspect loop. See also
AGENTS.md.
git clone https://github.com/bharathgnana/archdiagram.git
cd archdiagram && python -m tools.bootstrap2. As an MCP server
pip install "archdiagram[mcp]"
python -m mcp_server.server # stdio transportExposes list_templates, list_icons, resolve_service, get_catalog_info,
validate_spec, and generate_diagram, plus the earlier tool names as aliases.
The MCP tools use the same engine as the CLI. Details are in
docs/mcp_server.md. A sample client config is in examples/mcp.json
(drop it into .cursor/mcp.json or claude_desktop_config.json).
Repository layout
archdiagram/ pure-Python core (spec, layout, catalog, emitters)
mcp_server/ optional MCP server (only place the `mcp` SDK is used)
node/ optional Node bridge (resvg rasterise + svg->pdf)
tools/ icon downloader + icon source map
skill/ SKILL.md for agentic AI tools
examples/ sample specs + mcp.json
tests/ stdlib unittest suiteTests
python -m unittest discover -s testsContributing
Anyone can clone, install (pip install -e .), and use it. To propose changes,
fork and open a pull request - see CONTRIBUTING.md for the
dev setup and workflow.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP server for AI access to Swagger by SmartBear.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that generates professional infrastructure diagrams using the Python diagrams DSL, with first-class Azure support and GitHub Copilot integration for natural language diagram generation.4MIT
- FlicenseAqualityDmaintenanceMCP server exposing 3100+ cloud technology icons (AWS, Azure, GCP, Microsoft, CNCF, Devicon) with 3-tier search and multiple output formats for integration into presentations and architecture diagrams.7-
- AlicenseAqualityDmaintenanceMCP server for generating diagrams, charts, and visualizations using Gemini image generation on Vertex AI. Supports auto-detection of diagram types, multiple style modes, and iterative refinement.3104 npm1MIT
- FlicenseAqualityBmaintenanceAn MCP server that generates standalone SVG architecture diagrams from text descriptions, running entirely on your machine with no dependencies or network access.8-


