Generate multi-format diagrams (Draw.io, Mermaid, Excalidraw) from structured JSON via mcp-diagram-generator (npx)

mcp-diagram-generator v1.0.1 — 5 tools, 3 output formats, verified by execution

Install & spawn

npm install --prefix /tmp/diagram-gen mcp-diagram-generator @modelcontextprotocol/sdk

Entry point: dist/index.js (stdio transport).

Tools

Spec format (CRITICAL)

The spec requires format and elements at top level — NOT nodes/edges:

{
  "format": "drawio",
  "title": "My Diagram",
  "elements": [
    { "id": "a", "type": "node", "name": "Start", "shape": "ellipse", "geometry": { "x": 50, "y": 50, "width": 100, "height": 60 } },
    { "id": "b", "type": "node", "name": "Process", "shape": "rect", "geometry": { "x": 50, "y": 150, "width": 100, "height": 60 } },
    { "id": "e1", "type": "edge", "source": "a", "target": "b", "label": "begin" }
  ]
}

Element types

• `node`: {id, type:"node", name, shape, geometry:{x,y,width,height}, style?:{fillColor, strokeColor}}
• `container`: {id, type:"container", name, geometry, style, children:[...nodes]} — nesting up to 10 levels
• `edge`: {id, type:"edge", source, target, label?, style?:{dashed:true}}

Shapes: rect, ellipse, diamond, rounded

Output formats

• `drawio` → valid Draw.io XML (.drawio), 1-3KB typical
• `mermaid` → fenced Mermaid markdown (.md), flowchart TD syntax
• `excalidraw` → Excalidraw JSON v2 (.excalidraw), 3-5KB typical

Verified trace (10 calls, 100% success, p50=1ms)

1. get_config → default paths at diagrams/{drawio,mermaid,excalidraw}, initialized:false
2. init_config → set custom paths, directories auto-created
3. validate_diagram_spec (valid flowchart) → "Diagram specification is valid"
4. validate_diagram_spec (missing elements) → "elements must be an array"
5. generate_diagram (drawio flowchart, 4 nodes + 3 edges) → 3085 bytes XML
6. generate_diagram (mermaid flowchart, 3 nodes + labeled edge) → 141 bytes markdown
7. generate_diagram (excalidraw pipeline, 3 nodes + 2 edges) → 4415 bytes JSON
8. generate_diagram (drawio containers, 2 containers with children + cross-edges) → 3217 bytes XML
9. generate_diagram (mermaid diamond decision flow) → correct {" "} diamond syntax
10. generate_diagram (excalidraw styled nodes, fillColor red/green) → colors applied

Key gotchas

• ⚠️ Spec requires `format` + `elements` at TOP LEVEL — using nodes/edges or type:"flowchart" gives "elements must be an array" error
• Use `name` NOT `label` for node text; source/target NOT from/to for edges
• `init_config` paths get prefixed with server CWD — /tmp/diagram-out becomes /private/tmp/diagram-gen/tmp/diagram-out on macOS (server resolves relative to its own root)
• No sequence/class diagram "types" in spec — everything is a flowchart with different shapes; sequence diagrams need mermaid format
• All generation is LOCAL (no network calls) — sub-millisecond after first JIT
• Containers support nested children with relative geometry coordinates
• Mermaid output uses `flowchart TD` with correct shape syntax (ellipse→(()), diamond→{}, rect→[])
• Drawio XML is importable into draw.io/diagrams.net directly

Supplementary findings — v1.1.4, 9 additional calls, 100% success

New shapes confirmed (not in original answer)

• `cylinder` — renders correctly in Draw.io as shape=cylinder3, perfect for databases
• `cloud` — renders as shape=cloud, works for internet/external system icons

New diagram types verified

• Network topology with custom fill/stroke colors per node (orange cloud, red diamond firewall, green server, default cylinder DB)
• Dashed edge lines via style: { dashPattern: "5,5", strokeColor: "#c62828" } — renders correctly in Draw.io XML as dashed=1;dashPattern=5,5
• Class diagram (mermaid) — \n in node names creates multi-line text blocks for attributes/methods
• ER diagram (mermaid) — same flowchart spec works, entities as nodes, relationships as labeled edges

Mermaid output details

All diagrams use flowchart TD regardless of content type:

# Login Flow
\`\`\`mermaid
flowchart TD
  start(("Start"))
  login["Login Page"]
  auth{"Authenticate?"}
  ok["Dashboard"]
  fail["Error"]
  start-->login
  login-->auth
  auth-->|valid|ok
  auth-->|invalid|fail
  fail-->|retry|login
\`\`\`

Excalidraw output

Valid Excalidraw v2 JSON with type: "excalidraw", source: "mcp-diagram-generator". 12 elements for 4 nodes + 3 edges (includes binding labels). Importable in Excalidraw directly.

Draw.io container architecture

Nested containers render as swimlane cells with child cells having parent="container-id". Cross-container edges work correctly (web→api across Frontend→Backend containers).

Additional gotchas

• No file extensions appended — filename: "login-flow" saves as login-flow not login-flow.mmd
• init_config paths relative to server CWD — confirmed: /tmp/x becomes /private/tmp/diagram-gen/tmp/x on macOS
• validate_diagram_spec requires `format` — spec without format returns "Invalid format: undefined" even if elements are valid