@achmadya-dev/mcp-drawio

MCP server for draw.io. Create diagrams via LLM — rendered inline in chat using MCP Apps.

Built on @achmadya-dev/mcp-core and @modelcontextprotocol/ext-apps.

Requirements

Node.js ≥ 20
MCP host with MCP Apps support (e.g. Cursor)

Install via npx

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@achmadya-dev/mcp-drawio"]
    }
  }
}

Tools

Tool	Description
`show_inline_drawio`	Render a diagram inline in chat from Mermaid or draw.io XML
`search_shapes`	Search 10k+ industry icon shapes (AWS, Cisco, P&ID, …) for XML diagrams

search_shapes is registered when the bundled shape index is present (included in the npm package after build).

`show_inline_drawio`

Provide exactly one of mermaid or xml:

Input	Use for
`mermaid`	Flowchart, sequence, ER, class, state, gantt, mindmap, C4, and 25+ other types
`xml`	Hand-placed layouts, swimlanes, cloud/network/P&ID stencils, UI mockups

Optional layout passes (XML only):

Option	Effect
`postLayout: "elk"`	Re-layout vertices with ELK (flowcharts, pipelines, hierarchical diagrams)
`direction: "vertical" \| "horizontal"`	ELK flow direction (XML only; defaults to vertical)
`routing: "libavoid"`	Obstacle-avoiding edge routing without moving vertices

For industry icons in XML diagrams, call search_shapes first and use the returned style strings in mxCell attributes. References: xml-reference.md, mermaid-reference.md.

Inline viewer

The create_diagram tool renders an interactive iframe in chat:

Zoom, pan, and fit-to-view
Fullscreen mode
Open in draw.io — opens the diagram in app.diagrams.net for editing and export (PNG, SVG, PDF)

To save a diagram as an image, use Open in draw.io → File → Export as.

Develop from source

git clone https://github.com/achmadya-dev/mcp-drawio.git
cd drawio-mcp
pnpm install
pnpm run build
pnpm start

Local Cursor config (.cursor/mcp.json):

{
  "mcpServers": {
    "drawio": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

After changing viewer or server code, rebuild and restart the MCP server in Cursor.

Scripts

Command	Description
`pnpm run build`	Compile TypeScript and copy `src/assets/` → `dist/assets/`
`pnpm start`	Run MCP server (stdio)
`pnpm test`	Run tests
`pnpm run generate:shapes`	Regenerate shape search index (requires network)
`pnpm run format`	Format with Prettier

Environment

Variable	Description
`DOMAIN`	MCP Apps iframe domain (passed in resource `_meta.ui`)
`VIEWER_PATH`	Optional path to a local `viewer-static.min.js` override
`ELK_PATH`	Optional path to a local `drawio-elk.min.js` override
`MERMAID_PATH`	Optional path to a local `drawio-mermaid.min.js` override

The draw.io viewer loads from https://viewer.diagrams.net by default (CDN). Optional bundle overrides are useful for offline development or pinning a specific draw.io release.

Project layout

src/
  index.ts              MCP server entry (stdio, MCP Apps)
  drawio/
    drawio.ts           Bundle loader (HTML, shape index, references)
    utils.ts            createDiagram, searchShapes, validation
    viewer/html.ts      Inline MCP App viewer (draw.io + MCP SDK)
  tools/
    search_shapes.ts    Shape search tool (defineTool)
  assets/
    shared/             Tool description references (XML, Mermaid)
    shape-search/       Pre-built shape index (~10k shapes)
    vendor/app/         libavoid WASM (edge routing in viewer)
  scripts/
    copy-assets.ts      Build-time asset copy
    generate-shape-index.ts
dist/                   Published to npm

Diagram formats (quick guide)

Need	Approach
Flowchart, sequence, ER, class, …	Mermaid via `show_inline_drawio`
AWS / Azure / Cisco / P&ID icons	XML + `search_shapes`
Edit or export PNG/SVG	Open in draw.io in the inline viewer

libavoid vendor refresh

Browser WASM lives in src/assets/vendor/app/libavoid/. To refresh:

cd src/assets/vendor/app/libavoid
npm pack libavoid-js && tar -xzf libavoid-js-*.tgz
cp package/dist/index.js libavoid.min.js
cp package/dist/libavoid.wasm libavoid.wasm

Regenerate shape index (optional, when draw.io releases new shapes):

pnpm run generate:shapes
pnpm run build

Release

Uses Changesets:

pnpm changeset
pnpm run version-packages

Push to main → GitHub opens a Version packages PR → merge → npm publish via CI.

Requires NPM_TOKEN secret on the repository.

License

Apache-2.0

drawio