draw.io

Draw.io MCP 服务

官方的 draw.io MCP（模型上下文协议）服务，可让大模型在 draw.io 编辑器中创建和打开图表。

▶ 观看视频，并在 drawio.com/mcp 上为你的 AI 助手设置 draw.io。

创建图表的四种方式

此仓库提供四种将 draw.io 集成到 AI 助手中的方法。选择适合你配置的方式：

	MCP App Server	MCP Tool Server	助手插件	项目说明
工作方式	在聊天中内嵌呈现图表	在浏览器中打开图表	生成 .drawio 文件，可选导出为 PNG/SVG/PDF 或生成浏览器 URL	Claude 通过 Python 生成 draw.io URL
图表输出	嵌入对话的交互式查看器	新标签页中的 draw.io 编辑器	.drawio、.drawio.png / .svg / .pdf 或浏览器 URL	可点击的 draw.io 链接
是否需要安装	否（托管于 mcp.draw.io）	是（npm 包）	一行命令安装插件（仅导出 PNG/SVG/PDF 时需要 draw.io Desktop）	否 — 只需粘贴说明
支持 XML、CSV、Mermaid	XML 和 Mermaid	✅ 三者都支持	XML 和 Mermaid（Mermaid 需要 draw.io Desktop）	✅ 三者都支持
可在 draw.io 中编辑	通过“Open in draw.io”按钮	✅ 直接编辑	✅ 直接编辑	通过链接
适用于	Claude.ai、ChatGPT、VS Code、Cursor、GitHub Copilot CLI 及任何 MCP Apps 宿主	Claude Desktop、Cursor、OpenCode 及任何 MCP 客户端	Claude Code、Codex CLI、GitHub Copilot、Cursor、Antigravity、OpenCode	Claude.ai（搭配 Projects）
最适合	在聊天中内嵌预览	本地桌面工作流	本地开发工作流	快速设置，无需安装

---

指南

draw.io 文档中提供了经过测试的提示词和示例；每种助手的设置说明请参阅 drawio.com/mcp：

• 编写提示词：Mermaid 或 draw.io XML、速度和模型
• 图表类型和示例以及所有图表类型的图库
• 修改图表和设置样式：通过提示词进行修改、配色主题、样式
• 安装选项和输出格式
• 图表查看器

图库由 docs/images/gallery/gallery.json 及其旁边可编辑的浅色和深色 SVG 文件生成；构建网站时，drawio.com 会读取这些文件。

---

MCP 应用服务

MCP 应用服务使用 MCP Apps 协议，在 AI 聊天界面中内嵌呈现 draw.io 图表。图表不会在浏览器标签页中打开，而是以交互式 iframe 的形式直接显示在对话中。

官方托管端点如下：

https://mcp.draw.io/mcp

将此 URL 添加为 Claude.ai、ChatGPT、VS Code（GitHub Copilot）、Cursor、GitHub Copilot CLI 或任何兼容 MCP Apps 的宿主中的远程 MCP 服务，无需安装。在 Claude.ai 中，draw.io 也列在连接器目录中，可从那里一键添加。在 Cursor（≥ 2.6）中，图表会内嵌显示在 Agent 聊天中（一键安装）；在较早版本中，请改用 stdio @drawio/mcp 工具服务。在 GitHub Copilot CLI 中，运行 copilot mcp add --transport http drawio https://mcp.draw.io/mcp；终端无法内嵌显示图表，因此会提供链接，以便在 draw.io 中打开每个图表。

你也可以通过 Node.js 或 jgraph/drawio-mcp Docker 镜像在本地运行此服务，或者将自己的实例部署到 Cloudflare Workers。

工具：

• create_diagram — 将 draw.io XML 或 Mermaid（28 种图表类型）呈现为聊天中内嵌显示的交互式图表
• search_shapes — 按关键词搜索所有 draw.io 库中的 10,000 多种形状（AWS、Azure、GCP、P&ID、电气、Cisco、Kubernetes、UML、BPMN 等）；当内置库中没有合适匹配项时，还会通过 draw.io 图标服务补充搜索结果（品牌徽标和通用概念图标）。返回可直接用于 XML 的精确样式字符串。调用 create_diagram 前，请使用此工具查找正确的形状。
• get_drawio_reference — 返回 XML 或 Mermaid 生成参考，模型会在首次生成图表前按格式读取一次。

完整文档 →

注意： 在支持 MCP Apps 扩展的宿主中，例如 Claude.ai、ChatGPT、搭配 GitHub Copilot 的 VS Code 和 Cursor，图表会内嵌显示。在其他宿主中，例如 GitHub Copilot CLI，工具仍可正常工作，并会返回一个可在 draw.io 中打开图表的链接。

---

MCP 工具服务

原始 MCP 服务，可在 draw.io 编辑器中直接打开图表。支持 XML、CSV 和 Mermaid.js 格式，并提供灯箱和深色模式选项。已在 npm 上发布为 @drawio/mcp。

快速开始：npx @drawio/mcp

提供适用于 Claude Desktop、Claude Code、VS Code（GitHub Copilot）、Cursor（支持一键安装）和 OpenCode 的设置说明。

完整文档 →

---

助手插件（Claude Code、Codex CLI、GitHub Copilot）

以插件形式打包的 drawio 技能，适用于 AI 编码助手（位于 plugins/）：它会生成原生 .drawio 文件，也可选择导出为 PNG、SVG 或 PDF（嵌入 XML，因此导出的文件仍可在 draw.io 中编辑），或者生成可直接在 app.diagrams.net 中打开图表的浏览器 URL。Claude Code 和 Cursor 插件还打包了托管的 MCP App Server，因此在宿主支持的情况下，图表会以内嵌方式显示；Codex 和 Copilot 移植版无需设置 MCP。同一技能适用于四种宿主：

Claude Code（完整文档 →）——从此仓库的市场安装：

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

或者通过 claude --plugin-dir ./plugins/claude-code 从本地克隆直接加载。

Codex CLI（完整文档 →）——从同一市场仓库安装：

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

GitHub Copilot CLI（完整文档 →）——从同一市场仓库安装：

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

其他 Copilot 界面（VS Code Agent 模式、编码 Agent、代码审查）则从仓库的 .github/skills/ 目录加载同一技能——请参阅插件 README。

Cursor（完整文档 →）——同一技能加上托管的 MCP App Server，因此图表也会以内嵌方式显示在 Cursor 的 Agent 聊天中。可从 Cursor Marketplace（Customize → drawio → Install）安装，或者将 plugins/cursor 复制到 ~/.cursor/plugins/local/drawio，然后重新加载窗口。

Antigravity（完整文档 →）——从 GitHub 上的插件目录安装：

agy plugin install https://github.com/jgraph/drawio-mcp/tree/main/plugins/antigravity

OpenCode 无需插件：它会在 .opencode/skills/ 和 .claude/skills/（以及对应的 ~/ 目录）中查找技能，因此 Claude Code 技能文件夹可直接使用——单行安装方法请参阅 OpenCode（无需插件）。

默认情况下，插件会写入 .drawio 文件并在 draw.io 中打开。若要更改输出格式，请在请求中注明：

• png / svg / pdf — 使用 draw.io 桌面版 CLI 和 --embed-diagram 导出
• url — 使用 Node.js 内置的 zlib 压缩 XML，并在 app.diagrams.net 中打开结果。无需安装 draw.io Desktop；.drawio 文件会保留在本地，作为持久副本。

---

替代方案：项目指令（无需 MCP）

一种无需安装任何内容的替代方案。在 Claude Project 中添加指令，教 Claude 使用 Python 代码执行来生成 draw.io URL。无需 MCP 服务，也无需桌面应用——粘贴即可使用。

完整文档 →

---

图表布局

AI 生成图表后，可运行两种可选且相互独立的布局处理：一种会重新排列节点，另一种只会重新布线边。具体支持哪些处理方式取决于所选方案：

布局处理	功能	App Server（create_diagram）	Tool Server（open_drawio_xml）	助手插件	项目说明
ELK 自动布局（postLayout: "elk"）	将节点重新排列成整洁的分层布局；同时对边进行布线	✅	—	✅ 通过 draw.io Desktop CLI（--layout）	—
libavoid 布线（routing: "libavoid"）	保持节点位置不变；将连接线改为正交走线，绕开图形	✅	✅ 从 v1.3.0 起	✅ 通过 draw.io Desktop CLI（--layout libavoid）	—

• 这些处理适用于 draw.io XML 图表。Mermaid 图表已自动完成布局，因此无需使用这两种处理。
• App Server 会在图表渲染后，于内嵌查看器中应用这些处理；Tool Server 会在打开 draw.io 编辑器前于服务端应用 libavoid；插件 则通过本地安装的 draw.io Desktop CLI 运行这些处理。
• 二选一，不要同时使用：ELK 已经会为自己的边布线，再叠加 libavoid 是多余的。使用 postLayout 重新排列布局，或使用 routing 整理你已刻意放置的布局中的连接线。

---

数据驻留与离线使用

如果你要在数据限制严格的环境中部署，以下说明了每种方案下图表数据的确切去向。

没有任何组件会将你的图表发送给云端栅格化服务。 本仓库中不会调用 convert.diagrams.net（或任何云端导出端点），也不存在“本地依赖缺失 → 回退到云端”的路径。PNG/SVG/PDF 导出仅发生在助手插件中，这些插件会调用你本地安装的 draw.io Desktop CLI（通过 which drawio 定位）；如果未安装，则会保留 .drawio 文件，不会发送任何内容。

你的图表会离开本机吗？

方案	图表会离开本机吗？
MCP App Server — 托管版（mcp.draw.io）	会 — 图表会作为 MCP 请求发送到 draw.io 服务。改为自托管（见下文）即可将数据留在本地。
MCP App Server — 自托管（本地 Node、jgraph/drawio-mcp Docker 镜像，或你自己的 Cloudflare）	不会 — 由你的服务处理，并嵌入在由客户端渲染的 HTML 中。
MCP Tool Server（@drawio/mcp）	不会 — 数据位于 URL 的 #fragment 中，浏览器不会将其发送到服务端。
助手插件（Claude Code、Codex CLI、GitHub Copilot、Cursor、Antigravity）	不会 — 文件在本地写入，并由本地 draw.io Desktop CLI 导出。Claude Code 和 Cursor 插件也内置了托管版 App Server：使用它绘制的图表会发送到 mcp.draw.io（见上方对应行）。

默认情况下，服务不会将图表内容写入日志，只会记录请求元数据（方法、会话、状态、耗时）。只有在以 DEBUG=true 运行时，托管在 Cloudflare 上的 App Server 才会记录响应正文。

减少外部请求

即使图表本身保留在本地，渲染时默认仍会从 app.diagrams.net 和 viewer.diagrams.net 加载 draw.io Web 应用／查看器的代码。这些请求获取的是应用代码和资源，而不是你的图表，但仍然属于出站请求。若要减少或移除这些请求：

• **App Server：**构建时设置 VIEWER_PATH 环境变量，将查看器内嵌，而不是从 viewer.diagrams.net 加载。服务器端会在启动时和每天向 viewer.diagrams.net 执行一次版本检查（不发送数据，超时为 5 s，可安全阻止）；此外，除非设置 DRAWIO_ICON_SERVICE_URL=off，否则 search_shapes 会使用搜索词查询 icons.diagrams.net。
• Tool Server：将 DRAWIO_BASE_URL 环境变量设置为一个可自托管的 draw.io 实例。它的两个服务器端处理阶段也会从 viewer.diagrams.net 获取代码，每个 draw.io 版本获取一次，并按用户缓存：libavoid 路由核心（routing: "libavoid"，安装时也会预先加载）和 drawio-elk 包（postLayout: "elk"，首次使用时获取，可通过 DRAWIO_ELK_URL 覆盖）。不请求这些处理阶段就不会发出此类请求；无论哪种情况，图表都不会包含在请求中。
• **Assistant Plugins：**选择启用 url 输出模式时，会在 app.diagrams.net 打开图表（地址为硬编码，无法通过 DRAWIO_BASE_URL 设置等效地址）。如果需要避免该请求，请改用默认的 .drawio 输出或本地 Desktop 导出。

你的 LLM 是另一项独立的考量

图表由 LLM 生成。如果你使用托管模型，无论此 MCP 服务运行在哪里，图表内容都会在该服务提供商的云端生成。要实现端到端隔离，还需要使用本地托管的模型。

验证

确认部署不会发出任何出站请求的唯一可靠方法，是在阻止网络出口的情况下运行它（或监视浏览器的 Network 选项卡），并确认它仍能正常渲染。我们建议任何有严格隔离要求的部署都这样验证。

---

XML 参考（唯一可信来源）

draw.io XML 生成参考涵盖边路由、容器、图层、标签、元数据、深色模式、样式属性和 XML 格式良好性，统一保存在一个规范文件中：

shared/xml-reference.md

上述四种方式都将此文件用作 LLM 提示词的唯一可信来源：

方式	如何访问参考文档
MCP App Server	在启动／构建时读取该文件，并通过 get_drawio_reference 工具返回
MCP Tool Server	在启动时从仓库或通过 prepack 打包的副本读取该文件，并通过 get_drawio_reference 工具返回；open_drawio_xml 的描述中包含精简版 shared/xml-essentials.md
Assistant Plugins（Claude Code、Codex CLI、GitHub Copilot）	通过 GitHub 原始文件 URL 获取精简版 shared/xml-essentials.md，只有涉及图层、标签、元数据、表格、跨职能网格和深色模式颜色时才获取完整参考
Project Instructions	用户将精简版 shared/xml-essentials.md 复制到自己的 Claude Project 中，只有需要了解这些主题时才使用完整参考

更新 XML 生成指南时，请编辑 shared/xml-reference.md；更改会自动传递给所有使用方。如果更改涉及 shared/xml-essentials.md 中概括的规则，也请相应更新其中的内容。

---

形状搜索索引

search_shapes 工具由预构建的 draw.io 全部形状索引提供支持。该索引通过在 Node.js 中使用 jsdom 运行所有侧边栏调色板初始化流程，并捕获形状数据，从实时 draw.io 客户端（https://app.diagrams.net/js/app.min.js）生成。

draw.io 图标服务（icons.diagrams.net，也就是编辑器侧边栏使用的同一分组图标搜索）中的图标不包含在此索引中：当本地索引中没有与查询高度匹配的结果时，search_shapes 会实时查询该服务，并以 shape=image 样式返回图标。将 DRAWIO_ICON_SERVICE_URL 设为可自托管服务以覆盖端点，或设为 off 以禁用图标补充。

shape-search/search-index.json 已提交到仓库。更新形状搜索索引 GitHub Action 会在每次 draw.io 发布后（drawio-dev 会在构建完成后触发 drawio-release）以及每天作为备用方案，从已发布的 draw.io 客户端重新生成索引；如果形状有变化，就会创建拉取请求。合并后，工具服务器会从 CDN 获取该索引；托管应用服务器会将其打包，因此需要部署。

如需手动重新生成索引（例如，迭代索引生成器时）：

cd shape-search
npm install
npm run generate

# Rebuild the MCP App Server worker to embed the updated index
cd ../mcp-app-server
npm run build:worker

生成器会直接从公开的 draw.io Web 应用获取 app.min.js，因此无需在本地检出 draw.io 源代码。

---

开发

# MCP App Server
cd mcp-app-server
npm install
npm start

# MCP Tool Server
cd mcp-tool-server
npm install
npm start

相关资源

• draw.io - 免费在线图表编辑器
• draw.io Desktop - 桌面应用
• @drawio/mcp on npm - 此 npm 包
• drawio-mcp on GitHub - 源代码仓库
• Mermaid.js 文档
• MCP 规范
• MCP Apps 扩展