it-architecture — MCP server for architecture drawings

An MCP server that turns a text description of an IT architecture into a standalone .svg drawing, in a choice of visual styles.

It is built to run entirely on your VDI:

• No dependencies. Pure Python standard library — nothing to pip install, no wheels to get through a proxy. Python 3.8+ is all you need.

• No network. No rendering service, no headless browser, no icon CDN, no telemetry. The layout engine, the ~60 component icons and the SVG writer are all in this repository.

• No surprises in the output. Every SVG is self-contained: no <script>, no external fonts, no embedded rasters. Safe to commit to git, paste into Confluence/SharePoint, or open in Inkscape or a browser.

customer [user]     "Customer"                 ┌──────────┐      ┌──────────┐
alb      [lb]       "Application LB"           │ Customer │─────▶│   ALB    │─ ─ ▶ …
api      [service]  "Payments API"             └──────────┘      └──────────┘
customer -> alb : "HTTPS"
alb -> api

1. Install

Nothing to build — the checkout is the install.

Windows (C:\Tools\MCP)

cd C:\Tools\MCP
git clone <this-repo> mcp-architecture
cd mcp-architecture
py -3 -m itarch.cli render examples\three-tier.arch --style cloud

That writes %USERPROFILE%\architecture-diagrams\three-tier.svg. If it does, the MCP server will work too.

Linux / macOS

git clone <this-repo> ~/tools/mcp-architecture
cd ~/tools/mcp-architecture
python3 -m itarch.cli render examples/three-tier.arch --style cloud

Optionally install it as a command (itarch, itarch-mcp) — still zero dependencies: python -m pip install --user -e .

Related MCP server: Azure Diagram MCP Server

2. Connect it to your local CLI / AI tool

The server speaks JSON-RPC 2.0 and negotiates MCP protocol 2025-06-18, 2025-03-26 or 2024-11-05, whichever the client asks for. Two transports are available; pick the one your client's config wants.

A. HTTP — for clients configured with a url (pi.dev and similar)

Start the server, then point the client at it.

Windows — double-click scripts\start-mcp-http.bat, or:

C:\Tools\MCP\mcp-architecture\scripts\start-mcp-http.bat

Linux / macOS:

python3 -m itarch --http                      # 127.0.0.1:8787/mcp
python3 -m itarch --http --port 9000          # somewhere else

Client config (this is mcp.example.json):

{
  "mcpServers": {
    "it-architecture": {
      "url": "http://127.0.0.1:8787/mcp",
      "lifecycle": "eager",
      "directTools": true
    }
  }
}

Check it is up at any time — curl.exe http://127.0.0.1:8787/ returns a one-line health page.

lifecycle: eager means the client connects at startup, so the server has to already be listening. To start it automatically at logon (per-user Scheduled Task, no admin rights):

cd C:\Tools\MCP\mcp-architecture
powershell -ExecutionPolicy Bypass -File .\scripts\install-autostart.ps1
Start-ScheduledTask -TaskName 'it-architecture MCP'      # start now, don't wait for logon

-Port 9000, -OutputDir D:\diagrams and -Uninstall are supported.

B. stdio — for clients that launch the server themselves

Nothing to start by hand; the client spawns it. See mcp.stdio.example.json:

{
  "mcpServers": {
    "it-architecture": {
      "command": "python",
      "args": ["-m", "itarch"],
      "env": { "PYTHONPATH": "C:\\Tools\\MCP\\mcp-architecture" }
    }
  }
}

Claude Code has a shorthand for the same thing:

claude mcp add it-architecture --env PYTHONPATH=$HOME/tools/mcp-architecture -- python3 -m itarch
claude mcp list        # should show: it-architecture: connected

C. No MCP client at all

The same engine has a plain CLI:

itarch render mydiagram.arch --style blueprint -o ./docs/img
itarch render mydiagram.arch --all-styles          # one file per style
itarch check  mydiagram.arch                       # validate, don't draw
itarch convert mydiagram.arch --to json
itarch styles | itarch types | itarch guide

(Without pip install, use python3 -m itarch.cli ….)

3. Where files go

ITARCH_OUTPUT_DIR, falling back to ~/architecture-diagrams (on Windows, C:\Users\<you>\architecture-diagrams). Every call can override it with output_dir. Alongside each SVG the server writes a .arch source file, so a diagram can be edited and re-rendered later instead of being described from scratch.

Because the HTTP transport hands back file paths, the server and the client have to see the same filesystem — which they do when both run on your machine. That is the intended deployment; the server is not built to be shared.

Tools exposed over MCP

Layout is fully automatic — layering, ordering, crossing reduction, edge routing and group boxes. Coordinates are never part of the input.

The notation

title: Payments platform
subtitle: Target state, Q3
direction: LR                      # LR (default), RL, TB, BT

group vpc "Production VPC" [cloud] {
  group public "Public subnet" [zone] {
    alb [lb] "Application LB" : "TLS 1.3 termination"
  }
  group private "Private subnet" [zone] {
    api    [service]  "Payments API" : "Java 21" {badge: PCI}
    ledger [postgres] "Ledger" : "PostgreSQL 16" {shape: cylinder}
  }
}
customer [user] "Customer"

customer -> alb : "HTTPS"
alb -> api : "mTLS"
api -> ledger : "SQL" {style: dashed}
api <-> idp : "OIDC"

• Components: id [type] "Label" : "sublabel" {badge:…, shape:…, accent:…}

• Connections: -> <- <-> -- (no arrow) ..> (dotted) ==> (thick), chains (a -> b -> c), labels after :

• Groups nest freely; kinds are zone, cloud, region, cluster, onprem, external, plain

• # and // start comments

Everything is equally expressible as JSON — see examples/microservices.json, or call convert_notation.

Styles

Aliases work too: aws→cloud, gcp→material, dark→neon, print/bw→minimal, sketch→whiteboard, infra→blueprint.

Component icons

About 60 glyphs across clients, compute, network, storage, data, integration, security and ops — server, service, function, container, k8s, database, nosql, cache, bucket, queue, topic, stream, gateway, lb, cdn, firewall, waf, auth, secret, monitor, logs, ci, user, browser, mobile, mainframe, thirdparty, …

Everyday names are aliased, so postgres, rds, lambda, eks, kafka, s3, sqs, redis, splunk all resolve to the right glyph. Unknown types degrade to a plain box rather than failing.

Examples

python3 -m itarch.cli render examples/three-tier.arch   --style cloud
python3 -m itarch.cli render examples/network-zones.arch --style blueprint
python3 -m itarch.cli render examples/c4-context.arch    --style c4
python3 -m itarch.cli render examples/event-driven.arch  --all-styles

Development

python3 -m unittest discover -s tests -v

83 tests, no fixtures to install. They cover the DSL, the spec validator, the layout invariants (no overlapping nodes, groups contain their members, nothing escapes its band, content fits the declared canvas), SVG well-formedness for every style, XML escaping of untrusted labels, the MCP protocol handling including malformed input and protocol downgrade, and the HTTP transport driven over a real socket.

Layout, briefly

itarch/layout.py is a compact Sugiyama pipeline: DFS cycle-breaking → longest-path layering → dummy nodes for long edges → barycenter crossing reduction → one reserved cross-axis band per group (siblings that never share a layer share the space) → exact isotonic (PAVA) 1-D placement inside each band → group boxes → edge routing. Everything is computed in layer/cross coordinates and mapped to screen space at the very end, which is why LR/RL/TB/BT all come out of the same code path.

Adding a style

Add one entry to STYLES in itarch/styles.py. The renderer, layout engine and icon set need no changes.

Adding an icon

Add a draw function and one ICONS entry in itarch/icons.py. Glyphs are authored in a 0..100 box using plain SVG primitives.

Security notes

• On stdio the server opens no socket at all. On --http it binds 127.0.0.1 only by default and validates the Origin header, so a web page you happen to have open cannot reach it by DNS rebinding. There is no authentication, so --host 0.0.0.0 is for trusted networks only — the server warns you when you do it.

• It never reads a file it was not given a path to; the only writes are the .svg/.arch files in the output directory, with filenames sanitised to a single path component.

• Labels are XML-escaped, so text coming from a ticket or a log cannot inject markup into the drawing.

• Output is deterministic: the same input always produces byte-identical SVG, which keeps diagrams reviewable in git.