Drawarch

DrawArch MCP

Turn architecture prompts and reference images into portable, natively editable Draw.io files.

Your MCP host does the visual reasoning. DrawArch does the deterministic rendering, asset embedding, validation, and delivery.

Quick start · See the workflow · Architecture · Contribute

---

See what stays editable

This is not a screenshot pasted into a diagram. Containers, labels, icons, shapes, connector endpoints, ports, and waypoints remain separate native mxCell objects. Assets are embedded inside the .drawio file, so the result remains portable and editable offline.

[!IMPORTANT]

DrawArch does not call another LLM and does not require a second LLM API key. ChatGPT, Claude, Codex, Cursor, or another vision-capable MCP host analyzes the request or image and supplies the scene graph.

What DrawArch gives you

Reference-image recreation

Attach an architecture image to your MCP host and ask:

Recreate this image with DrawArch. Preserve its layout, labels, icons, grouping, and connector routing. Keep every visible object editable and use real icons where appropriate.

The host and DrawArch then follow a reviewable four-step loop:

1. Prepare — the host vision model calls prepare_reference_recreation with a typed absolute scene graph.
2. Review and approve — the user or host policy reviews layout and online asset sources; approval is bound to that exact revision.
3. Create — create_reference_drawio safely resolves and embeds assets, renders native cells, validates the file, and returns the .drawio resource.
4. Compare and revise — compare_reference_recreation measures structural coverage; the host adjusts the plan and repeats when needed.

flowchart LR

A[Prompt or reference image] --> B[Vision-capable MCP host] B -->|typed scene graph| C{DrawArch MCP} C --> D[Plan revision & approval] D --> E[Safe asset resolver] E --> F[Native Draw.io renderer] F --> G[Validation & comparison] G -->|portable resource| H[Editable .drawio file] G -. revise .-> B

In plain terms: your existing AI analyzes the image; DrawArch turns that analysis into a controlled, validated, editable file. The complete contract is demonstrated in examples/reference-recreation.json.

Why not just generate an image?

DrawArch optimizes for high-fidelity, editable reconstruction, not an opaque pixel replica. The host vision model can inspect the result, update geometry or styling, and render another immutable revision.

Quick start

Requires Node.js 20+ or Docker.

Run from npm

npx -y drawarch-mcp@0.2.0

DrawArch uses stdio by default. Diagnostics go to stderr, preserving stdout for MCP messages.

Add it to a local MCP host

{

"mcpServers": { "drawarch": { "command": "npx", "args": ["-y", "drawarch-mcp@0.2.0"], "env": { "DRAWARCH_OUTPUT_DIR": "/absolute/path/to/diagrams", "DRAWARCH_ONLINE_ASSETS": "false" } } } }

On Windows hosts that do not resolve npx directly, set command to npx.cmd. You can also use the source checkout and configure an absolute dist/src/index.js path.

Run from source

git clone https://github.com/Ajey95/drawarch-mcp.git

cd drawarch-mcp npm ci npm test npm run build

Then configure your host:

{

"mcpServers": { "drawarch": { "command": "node", "args": ["/absolute/path/to/drawarch-mcp/dist/src/index.js"], "env": { "DRAWARCH_OUTPUT_DIR": "/absolute/path/to/diagrams" } } } }

Run the published container

docker run --rm -p 3000:3000 \

-e DRAWARCH_API_KEY=replace-with-a-long-random-secret \ -e DRAWARCH_APPROVAL_SECRET=replace-with-another-random-secret \ -e DRAWARCH_ALLOWED_HOSTS=localhost,127.0.0.1 \ -e DRAWARCH_ALLOWED_ORIGINS=localhost,127.0.0.1 \ -v drawarch-data:/data \ ghcr.io/ajey95/drawarch-mcp:0.2.0

The container runs Streamable HTTP on http://localhost:3000/mcp. Its public health probe is GET /health; MCP and file downloads require the configured bearer token.

Local and remote hosts

DrawArch currently provides the deployable server and public container, not a managed hosted endpoint. Operators supply the HTTPS domain and infrastructure.

MCP tools

Architecture generation

Reference recreation

Asset and security model

Reference plans support four asset modes:

Remote image handling rejects URL credentials, non-HTTPS protocols, custom ports, private or reserved DNS answers, unsafe redirects, excessive byte/pixel sizes, and active SVG content. Raster images are decoded and re-encoded before embedding. Online assets retain provider and license metadata; users remain responsible for verifying third-party license terms.

HTTP deployments additionally support bearer authentication, host validation, origin validation, safe output paths, atomic writes, and revision-bound HMAC approval tokens. See SECURITY.md for deployment guidance and vulnerability reporting.

Environment variables

Development

npm ci

npm test # 83 tests at the 0.2.0 release npm run build npm run sample npm audit --audit-level=high npm pack --dry-run

The CI matrix verifies Node 20 and 22 on Windows and Linux and builds the production Docker image. Read docs/ARCHITECTURE.md for component boundaries a