@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