绘图
- 作者仓库星标 4,189
- 作者仓库 drawio-mcp
- 领域
- 设计与多媒体
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @jgraph · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows · WSL
- 运行环境要求
- Node.js
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Draw.io Diagram Skill
Generate draw.io diagrams as native `.drawio` files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io), or generate a browser URL that opens the diagram directly in the draw.io editor.
## How to create a diagram
1. **Generate draw.io XML** in mxGraphModel format for the requested diagram
2. **Write the XML** to a `.drawio` file in the current working directory using the Write tool
3. **Handle the requested output format**:
- `png` / `svg` / `pdf` → locate the draw.io CLI (see [draw.io CLI](#drawio-cli)), export with `--embed-diagram`, then delete the source `.drawio` file. If the CLI is not found, keep the `.drawio` file and tell the user they can install the draw.io desktop app to enable export, or use `url` mode instead, or open the `.drawio` file directly
- `url` → generate a browser URL from the XML and open it (see [Browser URL output](#browser-url-output)). Keep the `.drawio` file as a persistent local copy
- *(no format)* → no extra step; the `.drawio` file is the output
4. **Open the result** — the exported file if exported, the browser URL if `url`, or the `.drawio` file otherwise. If the open command fails, print the file path (or URL) so the user can open it manually
## Choosing the output format
Check the user's request for a format preference. Examples:
- `/drawio create a flowchart` → `flowchart.drawio`
- `/drawio png flowchart for login` → `login-flow.drawio.png`
- `/drawio svg: ER diagram` → `er-diagram.drawio.svg`
- `/drawio pdf architecture overview` → `architecture-overview.drawio.pdf`
- `/drawio url flowchart for user login` → opens browser at `app.diagrams.net` with the diagram, keeps `login-flow.drawio` locally
If no format is mentioned, just write the `.drawio` file and open it in draw.io. The user can always ask to export later.
### Supported export formats
| Format | Embed XML | Notes |
|--------|-----------|-------|
| `png` | Yes (`-e`) | Viewable everywhere, editable in draw.io |
| `svg` | Yes (`-e`) | Scalable, editable in draw.io |
| `pdf` | Yes (`-e`) | Printable, editable in draw.io |
| `jpg` | No | Lossy, no embedded XML support |
PNG, SVG, and PDF all support `--embed-diagram` — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.
## Browser URL output
When the user requests `url` format, generate a draw.io URL that opens the diagram directly in the browser editor at `app.diagrams.net` — no draw.io Desktop required.
### How it works
1. The `.drawio` file is written to disk as usual (gives the user a persistent local copy they can re-edit)
2. The XML is compressed with Node.js's built-in `zlib` and base64-encoded
3. The result is embedded in a `https://app.diagrams.net/#create=...` URL
4. The URL is opened in the default browser
This uses only Node.js built-in modules (`zlib`, `child_process`) — no external dependencies.
### URL generation
Run this `node -e` one-liner to read the `.drawio` file and print the URL (replace `DIAGRAM.drawio` with the actual filename):
```bash
URL=$(node -e '
const fs = require("fs");
const zlib = require("zlib");
const xml = fs.readFileSync(process.argv[1], "utf8");
const compressed = zlib.deflateRawSync(encodeURIComponent(xml)).toString("base64");
const payload = encodeURIComponent(JSON.stringify({ type: "xml", compressed: true, data: compressed }));
console.log("https://app.diagrams.net/?grid=0&pv=0&border=10&edit=_blank#create=" + payload);
' DIAGRAM.drawio)
```
The URL format matches the MCP Tool Server. Node.js's `zlib.deflateRawSync` and `pako.deflateRaw` both implement RFC 1951 and produce identical output, so URLs from either source are interchangeable.
### Opening the URL
| Environment | Command |
|-------------|---------|
| macOS | `open "$URL"` |
| Linux (native) | `xdg-open "$URL"` |
| WSL2 | Write a temp `.url` file, open via `cmd.exe` (see below) |
| Windows (native) | Write a temp `.url` file, open via `start` (see below) |
**Why the `.url` workaround on Windows/WSL2?** `cmd.exe`'s `start` command treats `&` as a command separator and strips everything after `#` in URLs. The diagram payload lives in the `#create=...` fragment, so passing the URL directly causes it to be silently lost. A `.url` shortcut file preserves the URL intact.
**macOS / Linux example:**
```bash
open "$URL" # macOS
xdg-open "$URL" # Linux
```
**WSL2 example:**
```bash
TMPFILE=$(mktemp --suffix=.url)
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMPFILE"
cmd.exe /c start "" "$(wslpath -w "$TMPFILE")"
```
**Windows (native) example:**
```cmd
echo [InternetShortcut] > %TEMP%\drawio.url
echo URL=%URL% >> %TEMP%\drawio.url
start "" "%TEMP%\drawio.url"
```
### After opening
Print the URL so the user can copy or share it, and confirm the local file path:
```
Opened in browser: <URL>
Local file: DIAGRAM.drawio
```
The `.drawio` file stays on disk so the user can re-edit it later, attach it elsewhere, or export it to an image format on demand.
### URL length
The URL embeds the full compressed diagram in its hash fragment. Very large diagrams may hit browser URL length limits (typically ~32K–2MB depending on the browser). For complex diagrams that exceed the limit, fall back to writing the `.drawio` file and opening it locally.
## draw.io CLI
The draw.io desktop app includes a command-line interface for exporting.
### Locating the CLI
First, detect the environment, then locate the CLI accordingly:
#### WSL2 (Windows Subsystem for Linux)
WSL2 is detected when `/proc/version` contains `microsoft` or `WSL`:
```bash
grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"
```
On WSL2, use the Windows draw.io Desktop executable via `/mnt/c/...`:
```bash
DRAWIO_CMD=`/mnt/c/Program Files/draw.io/draw.io.exe`
```
The backtick quoting is required to handle the space in `Program Files` in bash.
If draw.io is installed in a non-default location, check common alternatives:
```bash
# Default install path
`/mnt/c/Program Files/draw.io/draw.io.exe`
# Per-user install (if the above does not exist)
`/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe`
```
#### macOS
```bash
/Applications/draw.io.app/Contents/MacOS/draw.io
```
#### Linux (native)
```bash
drawio # typically on PATH via snap/apt/flatpak
```
#### Windows (native, non-WSL2)
```
"C:\Program Files\draw.io\draw.io.exe"
```
Use `which drawio` (or `where draw.io` on Windows) to check if it's on PATH before falling back to the platform-specific path.
### Export command
```bash
drawio -x -f <format> -e -b 10 -o <output> <input.drawio>
```
**WSL2 example:**
```bash
`/mnt/c/Program Files/draw.io/draw.io.exe` -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio
```
Key flags:
- `-x` / `--export`: export mode
- `-f` / `--format`: output format (png, svg, pdf, jpg)
- `-e` / `--embed-diagram`: embed diagram XML in the output (PNG, SVG, PDF only)
- `-o` / `--output`: output file path
- `-b` / `--border`: border width around diagram (default: 0)
- `-t` / `--transparent`: transparent background (PNG only)
- `-s` / `--scale`: scale the diagram size
- `--width` / `--height`: fit into specified dimensions (preserves aspect ratio)
- `-a` / `--all-pages`: export all pages (PDF only)
- `-p` / `--page-index`: select a specific page (1-based)
### Opening the result
| Environment | Command |
|-------------|---------|
| macOS | `open <file>` |
| Linux (native) | `xdg-open <file>` |
| WSL2 | `cmd.exe /c start "" "$(wslpath -w <file>)"` |
| Windows | `start <file>` |
**WSL2 notes:**
- `wslpath -w <file>` converts a WSL2 path (e.g. `/home/user/diagram.drawio`) to a Windows path (e.g. `C:\Users\...`). This is required because `cmd.exe` cannot resolve `/mnt/c/...` style paths.
- The empty string `""` after `start` is required to prevent `start` from interpreting the filename as a window title.
**WSL2 example:**
```bash
cmd.exe /c start "" "$(wslpath -w diagram.drawio)"
```
## File naming
- Use a descriptive filename based on the diagram content (e.g., `login-flow`, `database-schema`)
- Use lowercase with hyphens for multi-word names
- For export, use double extensions: `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` — this signals the file contains embedded diagram XML
- After a successful export, delete the intermediate `.drawio` file — the exported file contains the full diagram
- For `url` mode, keep the `.drawio` file (no double extension) — the URL is a view/edit handle and the local file is the persistent copy
## XML format
A `.drawio` file is native mxGraphModel XML. Always generate XML directly — Mermaid and CSV formats require server-side conversion and cannot be saved as native files.
### Basic structure
Every diagram must have this structure:
```xml
<mxGraphModel adaptiveColors="auto">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<!-- Diagram cells go here with parent="1" -->
</root>
</mxGraphModel>
```
- Cell `id="0"` is the root layer
- Cell `id="1"` is the default parent layer
- All diagram elements use `parent="1"` unless using multiple layers
## XML reference
For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, fetch and follow the instructions at:
https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
## Troubleshooting
| Problem | Cause | Solution |
|---------|-------|----------|
| draw.io CLI not found | Desktop app not installed or not on PATH | Keep the `.drawio` file and tell the user to install the draw.io desktop app, use `url` mode instead, or open the file manually |
| Export produces empty/corrupt file | Invalid XML (e.g. double hyphens in comments, unescaped special characters) | Validate XML well-formedness before writing; see the XML well-formedness section below |
| Diagram opens but looks blank | Missing root cells `id="0"` and `id="1"` | Ensure the basic mxGraphModel structure is complete |
| Edges not rendering | Edge mxCell is self-closing (no child mxGeometry element) | Every edge must have `<mxGeometry relative="1" as="geometry" />` as a child element |
| File won't open after export | Incorrect file path or missing file association | Print the absolute file path so the user can open it manually |
| Browser opens with empty diagram in `url` mode | `cmd.exe` stripped the `#create=...` fragment | Use the `.url` temp-file workaround on Windows/WSL2 (see [Opening the URL](#opening-the-url)) — never pass the URL directly to `cmd.exe /c start` |
| URL is too long for the browser | Very large diagram exceeds browser URL length limit | Fall back to writing the `.drawio` file and opening it locally |
## CRITICAL: XML well-formedness
- **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
- Escape special characters in attribute values: `&`, `<`, `>`, `"`
- Always use unique `id` values for each `mxCell`
章节与文件索引
按说明文件中的顺序排列。
如何创建图表
选择输出格式
支持的导出格式
浏览器URL输出
它是如何运作的
文件/命令 -> .drawio · png · svg · pdf · --embed-diagram · url · /drawio create a flowchart · flowchart.drawio
内容校验值 -> d12eac460ffa
当前原文的自动摘译,尚未人工审校。
如何创建图表
为请求的图表生成 mxGraphModel 格式的draw.io XML 使用写入工具将 XML 写入当前工作目录中的
.drawio文件处理请求的输出格式:png/svg/pdf→ 找到draw.io CLI(请参阅draw.io CLI),使用--embed-diagram导出,然后删除源.drawio文件。如果未找到 CLI,请保留.drawio文件并告诉用户可以安装draw.io 桌面应用程序以启用导出,或使用url模式,或直接打开.drawio文件选择输出格式
检查用户对格式首选项的请求。示例:
/drawio create a flowchart→flowchart.drawio/drawio png flowchart for login→login-flow.drawio.png/drawio svg: ER diagram→er-diagram.drawio.svg/drawio pdf architecture overview→architecture-overview.drawio.pdf支持的导出格式
格式 · 嵌入 XML · 注释
png· 是 (-e) · 随处可见,可在draw.io中编辑svg· 是(-e) · 可扩展,可在draw.io中编辑pdf· 是(-e) · 可打印,可在draw.io中编辑jpg· 否 · 有损,无嵌入式 XML 支持浏览器URL输出
当用户请求
url格式时,生成一个draw.io URL,该URL直接在浏览器编辑器中的app.diagrams.net打开图表 - 不需要draw.io桌面。它是如何运作的
.drawio文件照常写入磁盘(为用户提供可以重新编辑的持久本地副本) XML 使用 Node.js 的内置zlib和 base64 编码进行压缩 结果嵌入在https://app.diagrams.net/#create=...URL 中 在默认浏览器中打开 URL 这仅使用 Node.js 内置模块(zlib,child_process) — 没有外部依赖。