DrawArch MCP

DrawArch turns architecture descriptions and reference images into portable, natively editable diagrams.net (.drawio) files through the Model Context Protocol.

The connected ChatGPT, Claude, Codex, Cursor, or other MCP host does the visual reasoning. DrawArch does not require or call a second LLM API. It validates the host model's scene graph, resolves and safely embeds real icons or images, renders exact absolute geometry, checks fidelity, and returns the .drawio file directly as an MCP artifact.

Why DrawArch

• Recreate a supplied reference image as independent editable shapes, text, icons, containers, and connectors.

• Generate architecture diagrams from structured components and flows.

• Use bundled icons, opt-in Iconify-compatible online icons, user-provided images, or approved HTTPS image URLs.

• Keep every asset inside the .drawio file; outputs do not depend on hotlinks.

• Run locally over stdio or as a shared Streamable HTTP MCP server.

• Protect remote deployments with bearer authentication, host/origin allowlists, SSRF controls, size limits, SVG sanitization, and raster re-encoding.

• Preserve approved plans as immutable revisions and reject stale approval tokens.

Related MCP server: diagram-ai-generator

Quick start

Requires Node.js 20 or newer.

npx -y drawarch-mcp

Local MCP configuration:

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

For an unpublished checkout, run npm install && npm run build, then replace the command with node and the args with the absolute path to dist/src/index.js.

Reference-image workflow

Attach an image to your MCP host and ask it to recreate the image with DrawArch. The intended tool sequence is:

1. The host vision model analyzes the image and calls prepare_reference_recreation with an absolute scene graph.

2. The host or user reviews the plan and approved asset sources. An approved preparation returns a revision-bound token.

3. The host calls create_reference_drawio; DrawArch resolves and embeds assets, renders exact coordinates, validates the file, and returns it as a resource.

4. compare_reference_recreation reports structural coverage. The host can revise the plan and repeat until the target is met.

Each visible object remains editable. Connectors retain source/target attachment, ports, and waypoints. See the complete reference-plan example.

Run a shared remote MCP server

DRAWARCH_TRANSPORT=http \
HOST=0.0.0.0 \
PORT=3000 \
DRAWARCH_API_KEY=replace-with-a-long-random-secret \
DRAWARCH_APPROVAL_SECRET=replace-with-another-random-secret \
DRAWARCH_ALLOWED_HOSTS=drawarch.example.com \
DRAWARCH_ALLOWED_ORIGINS=chatgpt.com,claude.ai \
DRAWARCH_ONLINE_ASSETS=true \
npx -y drawarch-mcp

Endpoints:

• POST /mcp — Streamable HTTP MCP

• GET /health — public health probe

• GET /files/<safe-name>.drawio — authenticated output download

Connect ChatGPT or Claude to https://drawarch.example.com/mcp and set Authorization: Bearer <DRAWARCH_API_KEY> in the connector configuration. ChatGPT cannot directly spawn a local stdio process; use the remote server for ChatGPT, or a supported development tunnel while testing.

Docker:

docker build -t drawarch-mcp .
docker run --rm -p 3000:3000 \
  -e DRAWARCH_API_KEY=replace-me \
  -e DRAWARCH_APPROVAL_SECRET=replace-me-too \
  -e DRAWARCH_ALLOWED_HOSTS=localhost,127.0.0.1 \
  -v drawarch-data:/data \
  drawarch-mcp

Or use the published image: ghcr.io/ajey95/drawarch-mcp:0.2.0.

MCP tools

Asset modes

Reference assets support four explicit modes:

• bundled: a DrawArch-owned MIT SVG selected by query.

• online: an Iconify-compatible SVG selected by query; server opt-in is required.

• data: a user-supplied SVG, PNG, JPEG, or WebP data URI.

• remote: an approved HTTPS image URL; server opt-in is required.

Remote fetching rejects credentials, non-HTTPS URLs, custom ports, private/reserved DNS answers, unsafe redirects, oversized content, active SVG content, and excessive raster dimensions. Raster images are decoded and re-encoded before embedding. Online assets retain their provider/license metadata; users remain responsible for verifying third-party license terms.

Configuration

Development

npm install
npm test
npm run build
npm run sample
npm pack --dry-run

Architecture and security details are in ARCHITECTURE.md. Contributions are welcome; read CONTRIBUTING.md, SECURITY.md, and the Code of Conduct.

License

DrawArch code and bundled assets are MIT licensed. Third-party assets keep their own provider licenses and attribution.