@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