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