Draw.io Scientific Illustrator

中文说明 · English guide · MIT License

A Codex plugin that lets an AI agent draw scientific figures live inside the visible draw.io desktop canvas. You can watch shapes, labels, arrows, styling, and layout appear step by step. The live workflow calls draw.io's own graph API through a localhost-only MCP server; it does not automate the operating-system mouse or keyboard and does not create XML first and merely open it afterward.

Status: Windows is tested. macOS and Linux executable discovery is included, but live behavior can vary with draw.io/Electron packaging. Reports and pull requests are welcome.

English guide

What this repository contains

• drawio-live MCP server: launches/connects to the visible draw.io desktop editor and edits its active graph model in real time.

• drawio-file-utils MCP server: validates saved .drawio documents and exports PNG, SVG, PDF, or JPG deliverables.

• A Codex skill: teaches the agent to inspect a reference, decompose it into editable primitives, draw with pacing, visually review sections, refine the live graph, and save only after the visible drawing exists.

• A repository-local Codex marketplace so the complete plugin can be installed as one unit.

This is therefore both an MCP implementation and a Codex plugin. MCP provides the callable tools; the plugin is the installable package containing the MCP servers, skill, and presentation metadata.

Requirements

1. Codex desktop app or Codex CLI with plugin support.

2. draw.io desktop installed locally.

3. Git.

4. Node.js available as node when running the MCP servers outside the bundled Codex runtime. Node.js 22 or newer is recommended.

The plugin auto-detects common draw.io locations on Windows, macOS, and Linux. For a custom installation, set DRAWIO_PATH to the executable before starting Codex.

Install — easiest methods

Ask Codex to install it

Paste this into a Codex task that has terminal access:

Install the public Codex plugin from https://github.com/icebird1998/drawio-scientific-illustrator.
Clone it locally, register its repository root as a Codex marketplace, install
drawio-scientific-illustrator@drawio-scientific-tools, then tell me when to restart Codex.

Windows one-command installer

Review install.ps1, then run:

$p="$env:TEMP\drawio-scientific-install.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p

macOS/Linux one-command installer

Review install.sh, then run:

curl -fsSL https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.sh | bash

Restart Codex and start a new task after installation so the new skill and MCP tools are loaded.

Install — manual and auditable

git clone https://github.com/icebird1998/drawio-scientific-illustrator.git
cd drawio-scientific-illustrator
codex plugin marketplace add "$(pwd)"
codex plugin add drawio-scientific-illustrator@drawio-scientific-tools

On PowerShell, replace "$(pwd)" with (Get-Location).Path:

git clone https://github.com/icebird1998/drawio-scientific-illustrator.git
Set-Location drawio-scientific-illustrator
codex plugin marketplace add (Get-Location).Path
codex plugin add drawio-scientific-illustrator@drawio-scientific-tools

How to use it

1. Restart Codex after installation and create a new task.

2. Attach a PNG, JPEG, SVG, or a rendered PDF page as the reference.

3. Mention Draw.io Scientific Illustrator or select the plugin in the composer.

4. State the desired pacing and output formats.

Recommended prompt:

Use Draw.io Scientific Illustrator. Launch the live draw.io canvas and recreate this
reference scientific figure step by step with a 100 ms delay. Control only draw.io's
own graph API; do not use OS mouse/keyboard automation and do not generate XML first.
Keep all labels, arrows, panels, and legends editable. Visually inspect and refine each
section, then save the final .drawio file and export a 2000 px PNG preview.

Chinese prompts work equally well:

使用 Draw.io Scientific Illustrator。启动实时 draw.io，以 100 ms 的步骤间隔重绘
这张参考图。必须直接控制 draw.io 画布，不要使用系统鼠标键盘控制，也不要先生成
XML。文字、箭头、分区和图例都要可编辑；完成后保存 .drawio 并导出 2000 px PNG。

Live tool workflow

The agent normally uses the tools in this order:

1. drawio_live_launch — launch or connect to a visible draw.io editor.

2. drawio_live_status — confirm that the graph is ready.

3. drawio_live_add_shape, drawio_live_add_edge, or paced drawio_live_draw_sequence — construct editable content visibly.

4. drawio_live_screenshot — inspect the draw.io renderer after logical sections.

5. drawio_live_inspect and drawio_live_update_cell — correct labels, styles, positions, and sizes.

6. drawio_live_fit — keep the evolving figure in view.

7. drawio_live_save_snapshot — serialize the already-visible graph to .drawio.

8. drawio_validate and drawio_export — validate and export deliverables.

Configuration

Optional environment variables:

Example on Windows:

$env:DRAWIO_PATH = "D:\Apps\draw.io\draw.io.exe"

Update

Run the same installer again. It performs a fast-forward git pull and reinstalls the plugin. Restart Codex and start a new task afterward.

Troubleshooting

• node not found: install Node.js 22+ or make sure the Codex runtime exposes Node to plugin MCP servers.

• draw.io not found: install the desktop app or set DRAWIO_PATH.

• Port already in use: omit an explicit port and the server will select a nearby localhost port, or set DRAWIO_LIVE_PORT to a free port.

• Graph not ready: close stale draw.io windows launched by the plugin, retry, and ensure the desktop app accepts Electron remote-debugging flags.

• Plugin not visible: restart Codex and create a new task after installation.

• Export fails: confirm that draw.io desktop can export the same file manually and that the output directory is writable.

Security and privacy

• The live debugging endpoint binds to 127.0.0.1, not a public network interface.

• Target discovery accepts only pages identified as draw.io/diagrams.net; it does not attach to arbitrary browser pages.

• The plugin does not use OS-level mouse or keyboard automation.

• No telemetry or hosted backend is included. See PRIVACY.md.

• Only install software from repositories and revisions you trust. Review the installer scripts before executing them.

Known limitations

• The live API currently emphasizes editable draw.io primitives. Dense microscopy images, photographs, heatmaps, and complex plots may need a future dedicated live image-insertion operation.

• Visual fidelity depends on reference resolution and how well the content can be represented by draw.io primitives.

• Windows is the tested platform for v1.0.0; macOS/Linux support is best effort until community testing expands.

Related MCP server: Draw.io MCP Server

中文说明

这是什么

Draw.io Scientific Illustrator 是一个面向科研插图的 Codex 插件。它会启动桌面版 draw.io，并通过仅限本机的 MCP 通道直接调用 draw.io 自身的图模型 API。你可以亲眼看到形状、文字、箭头、配色和布局按步骤出现在画布上。

它不会模拟系统鼠标或键盘，也不会先生成一个 XML 文件再让 draw.io 打开。只有当可见画布中的图已经绘制完成后，才会把当前图模型保存为 .drawio 文件。

这个仓库同时包含：

• 实时控制 draw.io 画布的 drawio-live MCP；

• 校验和导出的 drawio-file-utils MCP；

• 指导 Codex 重绘、检查和迭代科研插图的 Skill；

• 可供 Codex 安装的自定义插件市场配置。

所以它既“属于 MCP”，也属于更上层的“Codex 插件”：MCP 是实际工具接口，插件是把 MCP、Skill 和界面元数据打包分享的安装单位。

安装要求

1. 支持插件的 Codex 桌面应用或 Codex CLI；

2. 本机已安装 draw.io 桌面版；

3. Git；

4. 如果脱离 Codex 自带运行环境单独启动 MCP，需要可用的 Node.js，推荐 Node.js 22 或更高版本。

插件会自动检测 Windows、macOS 和 Linux 的常见 draw.io 安装位置。若安装在自定义目录，请在启动 Codex 前设置 DRAWIO_PATH。

最省事的安装方式

在一个具备终端权限的 Codex 任务里直接粘贴：

请安装这个公开 Codex 插件：https://github.com/icebird1998/drawio-scientific-illustrator。
把仓库克隆到本地，将仓库根目录注册为 Codex Marketplace，然后安装
drawio-scientific-illustrator@drawio-scientific-tools。完成后告诉我何时重启 Codex。

Windows 用户也可以先检查 install.ps1，然后运行：

$p="$env:TEMP\drawio-scientific-install.ps1"; Invoke-WebRequest https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.ps1 -OutFile $p; powershell -ExecutionPolicy Bypass -File $p

macOS/Linux 用户先检查 install.sh，然后运行：

curl -fsSL https://raw.githubusercontent.com/icebird1998/drawio-scientific-illustrator/main/install.sh | bash

安装完成后必须重启 Codex，并新建一个任务，使新的 Skill 和 MCP 工具被载入。

手动安装

PowerShell：

git clone https://github.com/icebird1998/drawio-scientific-illustrator.git
Set-Location drawio-scientific-illustrator
codex plugin marketplace add (Get-Location).Path
codex plugin add drawio-scientific-illustrator@drawio-scientific-tools

macOS/Linux：

git clone https://github.com/icebird1998/drawio-scientific-illustrator.git
cd drawio-scientific-illustrator
codex plugin marketplace add "$(pwd)"
codex plugin add drawio-scientific-illustrator@drawio-scientific-tools

使用方法

1. 重启 Codex 并新建任务；

2. 上传 PNG、JPEG、SVG，或者从 PDF 渲染出的参考页；

3. 在输入框选择或提到 Draw.io Scientific Illustrator；

4. 说明绘制步进间隔、画面尺寸和希望导出的格式。

推荐提示词：

使用 Draw.io Scientific Illustrator。启动实时 draw.io，以 100 ms 的步骤间隔逐步重绘
这张参考图。必须直接控制 draw.io 自己的画布 API，不要控制系统鼠标键盘，也不要先
生成 XML。所有文字、箭头、分区、图例都要保持可编辑。每完成一个逻辑区域就检查并
修正，最后保存 .drawio，并导出宽度为 2000 px 的 PNG 预览图。

工作过程

正常情况下，Codex 会依次完成：

1. 启动可见的 draw.io；

2. 确认内部 graph 已就绪；

3. 逐个或按设定间隔添加可编辑形状和连线；

4. 每完成一个逻辑区域截取 draw.io 渲染区域进行检查；

5. 直接在实时画布中修改文字、样式、位置和大小；

6. 完成后才保存 .drawio 快照；

7. 校验文件结构并导出 PNG、SVG、PDF 或 JPG。

可选配置

Windows 示例：

$env:DRAWIO_PATH = "D:\Apps\draw.io\draw.io.exe"

更新

再次运行安装脚本即可。脚本会执行安全的快进更新并重新安装插件。随后重启 Codex、新建任务。

常见问题

• 找不到 Node：安装 Node.js 22+，或确认 Codex 插件运行环境能够调用 node。

• 找不到 draw.io：安装桌面版，或者设置 DRAWIO_PATH。

• 端口被占用：不要强制指定端口，让插件自动选择；也可以修改 DRAWIO_LIVE_PORT。

• 图模型没有就绪：关闭插件此前启动但已失效的 draw.io 窗口后重试。

• 安装后看不到插件：重启 Codex，并新建任务。

• 导出失败：确认 draw.io 桌面版可以手工导出该文件，并检查输出目录写权限。

安全与隐私

• 实时调试端口仅绑定 127.0.0.1；

• 只接受可识别为 draw.io/diagrams.net 的页面，不会连接任意浏览器页面；

• 不使用系统级鼠标键盘自动化；

• 不包含遥测或云端服务，详见 PRIVACY.md；

• 执行远程安装脚本前，请先检查脚本内容和版本。

当前限制

• 实时工具目前主要面向可编辑的 draw.io 图元。显微照片、热图和复杂数据图可能需要后续增加专门的实时图片插入工具；

• 最终还原度取决于参考图分辨率，以及内容是否适合用 draw.io 图元表达；

• v1.0.0 已在 Windows 上测试，macOS/Linux 暂为尽力支持，欢迎提交测试反馈。

Contributing / 参与贡献

Issues and pull requests are welcome. Please include operating system, draw.io version, Codex version, reproduction steps, and relevant MCP error text. Do not upload confidential reference images.

欢迎提交 Issue 和 Pull Request。请注明操作系统、draw.io 版本、Codex 版本、复现步骤及相关 MCP 错误；不要上传保密的参考图片。

License

MIT © 2026 icebird1998