Skip to content

README.md

Latest commit

 

History

History
108 lines (71 loc) · 6.4 KB

README.md

File metadata and controls

108 lines (71 loc) · 6.4 KB
Raw

Draw.io Plugin for Claude Code

A Claude Code plugin that generates native .drawio files. Claude authors each diagram as Mermaid (converted and laid out by the draw.io desktop CLI) or as draw.io XML directly — with optional ELK auto-layout for XML, export to PNG/SVG/PDF (with embedded XML so the file remains editable in draw.io), or a browser URL that opens the diagram directly in app.diagrams.net. No MCP setup required.

How It Works

When you ask Claude Code to create a diagram, it will:

  1. Choose how to author it — Mermaid for standard types (flowchart, sequence, class, state, ER, gantt, mindmap…) when the desktop app is installed, or draw.io XML for custom styling, precise positioning, specific shape libraries, or when no desktop app is present
  2. Produce a native .drawio file — convert the Mermaid with the desktop CLI, or write the XML directly (optionally running an ELK --layout pass so you don't hand-place cells)
  3. Handle the requested output:
    • PNG / SVG / PDF — export using the draw.io desktop CLI
    • url — compress the XML with Node.js's built-in zlib and open https://app.diagrams.net/#create=... in your browser (keeps the .drawio file as a local copy)
    • (default) — leave the .drawio file as-is
  4. Open the result

Prerequisites

  • Claude Code installed
  • draw.io Desktop installed — required for Mermaid conversion, ELK layout, and PNG/SVG/PDF export. Not needed for plain XML .drawio or url output, which Claude can produce with no desktop app

Installation

Via the drawio marketplace (recommended)

Inside Claude Code, add this repository as a plugin marketplace, then install:

/plugin marketplace add jgraph/drawio-mcp
/plugin install drawio@drawio

The marketplace manifest lives at .claude-plugin/marketplace.json at the repo root and points at this directory.

Local development

To load the plugin directly from a local clone (e.g. while iterating on the skill):

claude --plugin-dir ./plugins/claude-code

The plugin loads the drawio skill from skills/drawio/SKILL.md — nothing else needs to be copied into your ~/.claude/skills/ directory.

Usage

In most cases you don't type a command at all — just ask Claude Code for a diagram ("draw a flowchart for user login") and the skill triggers automatically from its description. To invoke it explicitly, Claude Code namespaces plugin skills as /<plugin>:<skill>, so the command is /drawio:drawio:

/drawio:drawio create a flowchart for user login

(The first drawio is the plugin name, the second is the skill folder. Any skills added to this plugin later — e.g. /drawio:search-shapes — share the same prefix.)

By default, this writes a .drawio file and opens it in draw.io. To export to an image format or open the diagram in the browser, mention the format in your request:

/drawio:drawio png flowchart for user login       → login-flow.drawio.png
/drawio:drawio svg: ER diagram for e-commerce     → er-diagram.drawio.svg
/drawio:drawio pdf architecture overview          → architecture-overview.drawio.pdf
/drawio:drawio url flowchart for user login       → opens app.diagrams.net in browser, keeps login-flow.drawio locally

More examples:

/drawio:drawio sequence diagram for API auth
/drawio:drawio png class diagram for the models in src/
/drawio:drawio url architecture overview

Output Formats

Format Output Editor Dependency
(default) .drawio file draw.io Desktop, or the browser app None
png .drawio.png (embedded XML) draw.io Desktop, or any viewer draw.io Desktop (for export)
svg .drawio.svg (embedded XML) draw.io Desktop, or any viewer draw.io Desktop (for export)
pdf .drawio.pdf (embedded XML) draw.io Desktop, or any PDF viewer draw.io Desktop (for export)
url Browser tab at app.diagrams.net + .drawio file kept locally draw.io editor in browser Node.js (bundled with Claude Code)

The .drawio.* double extension signals that the file contains embedded diagram XML. Open any of these in draw.io to recover and edit the full diagram. The intermediate .drawio source file is deleted after image export since the exported file contains the complete diagram. In url mode, the .drawio file is kept so you have a persistent local copy to re-edit or share.

url mode uses only Node.js's built-in zlib (deflate-raw compression) and child_process (browser open) — no external dependencies. The resulting https://app.diagrams.net/#create=... URL is the same format used by the MCP Tool Server, so behavior is identical.

References

The skill fetches two shared guides from GitHub at runtime — the single source of truth for all draw.io MCP prompts across the repository. No extra files need to be copied during installation.

  • shared/xml-reference.md — draw.io XML generation (edge routing, containers, layers, tags, metadata, dark mode, etc.), used when authoring XML
  • shared/mermaid-reference.md — Mermaid syntax for all supported diagram types plus flowchart styling, used when authoring Mermaid

Authoring: Mermaid or XML?

A .drawio file is native mxGraphModel XML. Claude produces one two ways:

  • Mermaid — terse text that the desktop CLI converts to .drawio and lays out automatically. Preferred for standard diagram types when the desktop app is installed.
  • XML — generated directly, for custom styling, precise positioning, or specific shape libraries. Needs no desktop app, so it's the universal fallback (.drawio file or url).

Both routes end up as the same native .drawio format, immediately editable in draw.io. Mermaid conversion and ELK layout run locally via the desktop CLI — there is no server dependency.

Other Variants

This repository offers multiple ways to integrate draw.io with AI assistants: