← Docs home
drawio
  1. Overview
  2. How it works
  3. Pipeline
  4. Gallery
  5. Under the hood
  6. Findings
  7. Build your own
  8. Sources
Skill explainer · jgraph/drawio-mcp

Draw.io

Every diagram becomes a native .drawio file first, then whatever format you asked for.

The official draw.io skill, shipped byte-identical to Claude Code, Codex, Copilot, Cursor and Antigravity. Author as Mermaid or XML, repair it, lay it out with ELK, and export with the XML embedded so every PNG stays editable. I read the skill, ran both servers’ test suites and the shared modules. Every diagram becomes a native .drawio file first, then is delivered in the requested output format, whether you authored Mermaid or XML.

05c1747commit, 22 Oct 2026
5byte-identical ports
6ELK presets
5output formats
8MCP tools
201/201tests pass

Who it is for

Agents in terminals (Claude Code, Codex, Copilot CLI) where diagrams cannot render inline.

What you get

A .drawio, an embedded-XML PNG/SVG/PDF, or an app.diagrams.net link.

How It Works

Author, Repair, Lay Out, Deliver

The skill is one pipeline with two ways in.

1

Inline first. Inline viewer first. In chats that render diagrams, the MCP create_diagram tool wins.

2

Author. Mermaid when the desktop CLI exists; XML otherwise. If Mermaid was requested but no desktop CLI is available, author the same diagram as XML.

3

Repair. It changes nothing in a well-formed file, and needs only Node.js.

4

Lay out. The CLI's --layout step auto-positions XML-authored diagrams with the same ELK layouts as the editor's Arrange ▸ Layout menu and the draw.io MCP app server.

5

Deliver. Exports use double extensions so the name says the XML is inside.

The Pipeline

Fifteen Choices, One Artifact

Pick an authoring route, a layout or an output. Quotes are checked against SKILL.md at build time.

Under The Hood

Eight Shared Modules Feed Two Servers

The skill’s inline repair step is a small version of repair-xml.js. I imported each module and ran it on test input.

What I Found Running It

Thoroughly Tested; The CLI Is The Dependency

All runs used a copy of the repo in /tmp, with nice and timeout, at commit 05c1747.

RunResultNote
mcp-tool-server npm test125/125 passAbout 1 s.
mcp-app-server npm test76 pass, 2 skippedSkipped tests need a live Worker (EDGE_COMPARE_URL).
SKILL.md repair one-linerfixedProse, fence, unescaped label and self-parented layer.
SKILL.md URL one-linerround-trips247-character link for a tiny diagram.
Shared modulesworkrepair, normalize, mermaid-elk and shape search all behaved as documented.
5 SKILL.md portsbyte-identicalA CI workflow enforces it.
draw.io Desktop CLInot on the boxMermaid conversion, layout and export need it.

Gap Mermaid, layouts and export all need the desktop app

Without it the skill can only write XML and a URL. The skill says so and falls back cleanly.

Gap References load from main, unpinned

SKILL.md tells the agent to fetch xml-essentials.md and mermaid-reference.md from raw.githubusercontent.com/…/main, so a skill pinned at one commit reads rules from another.

Cost Two repair implementations

The inline one-liner and repair-xml.js do overlapping work; only the module reports what it changed or handles leaked tool-call tags.

Bug Shape search ranks a number first

“cisco router” returns a stencil titled “10700” above “ATM Router”.

Copy Editable exports

-e embeds the XML, and the double extension tells people it is there.

Copy Port parity in CI

One workflow fails the build if any port’s SKILL.md drifts from the Claude Code copy.

Build Your Own

What To Steal

  1. One native artifact, many deliveries. Write the source format first; derive the rest.

  2. Prefer a layout engine to model coordinates. Ask for structure, not positions.

  3. Measure the model’s mistakes, then fix them in code. repair-xml.js says its three fixes covered all 15 broken diagrams out of 473.

  4. Detect the environment exhaustively. The Windows chain checks PATH, install paths, registry and other drives before giving up.

  5. Keep ports identical by CI.

Sources

Everything Here Is Checked

Each quote on this page is compared with its source file at build time; the build fails on any mismatch.

  1. plugins/cursor/skills/drawio/SKILL.md
  2. mcp-tool-server/src/index.js
  3. shared/repair-xml.js
  4. .github/workflows/check-skill-sync.yml
  5. github.com/jgraph/drawio-mcp