进阶约 25 分钟 2026-10-08 17:27:54 · 2 阅读

draw.io MCP 接入实战：让 AI 在聊天里画架构图，四条路径与两个工具

画图这件事，可以让 AI 代劳摆盒子

画架构图最磨人的往往不是想清楚结构，而是摆盒子、拉连线、对齐。draw.io 官方开源的 MCP 服务器把这一步交了出去：你在 Claude、Cursor 这类 AI 客户端里描述结构，服务器生成图，图要么直接内嵌在对话里渲染，要么一键打开到 draw.io 编辑器继续改。这篇讲清楚两件事：四条接入路径怎么挑，两个工具怎么调。同类的 AI 工具接入教程站内已有不少，画图这一块此前一直空着。

先说结论：只想快速体验，选免安装的托管端点；要让图在本地工作流里落地成文件，选 npm 本地服务器。两条路径覆盖九成需求，另外两条（插件、项目指令）面向特定客户端，文末一并说清。

这个仓库提供了什么

jgraph/drawio-mcp 是 draw.io 母公司 jgraph 维护的官方 MCP 实现，Apache-2.0 协议，GitHub 上 5.6k star（2026-10-08 实时 5589）。README 把接入方式整理成四条，各自输出形态不同：

方式	图表输出	要装什么	适合谁
MCP App Server	聊天窗口内嵌交互视图	什么都不装，加个 URL	想在对话里直接看图的人
MCP Tool Server	浏览器新标签打开 draw.io 编辑器	npm 包（npx 一行）	本地桌面工作流
Assistant Plugins	原生 .drawio 文件，可选导出 PNG/SVG/PDF	一行插件安装命令	Claude Code / Codex CLI / Copilot 用户
Project Instructions	可点击的 draw.io 链接	什么都不装，粘贴指令	只用 Claude.ai Projects 的人

前两条是 MCP 服务器，工具能力最强，是本文主线；后两条本质上不依赖 MCP，属于轻量替代方案。

免安装路径：托管端点加进客户端

App Server 的官方托管端点就一个地址：

https://mcp.draw.io/mcp

在 Claude.ai 里，可以从连接器目录搜 draw.io 一键添加；Cursor（2.6 及以上）提供了官方一键安装按钮，也可以手动把地址写进 ~/.cursor/mcp.json（全局）或项目里的 .cursor/mcp.json：

{
  "mcpServers": {
    "drawio": {
      "url": "https://mcp.draw.io/mcp"
    }
  }
}

写完在弹出的提示里启用服务器（或到 Cursor Settings → MCP 里开），然后直接让 Agent 画一张图试试。

OpenCode 的写法略有不同，远程服务器要放在 opencode.json 的 mcp 键下并声明 type: "remote"：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "drawio": {
      "type": "remote",
      "url": "https://mcp.draw.io/mcp",
      "enabled": true
    }
  }
}

有一处兼容性要知道：内嵌渲染依赖 MCP Apps 扩展，宿主不支持时工具照样连得上，但聊天里没有渲染位，返回的只是 XML 文本。README 点名 VS Code / GitHub Copilot 和 Claude Code 属于这类，ChatGPT 也暂不支持（它的连接器走 OpenAI 自己的组件格式）。这些客户端请改用下面这条本地路径。

本地路径：npx 起 stdio 服务器

Tool Server 是最早的一版实现，图表不内嵌，而是压缩进 URL 后在浏览器里打开 draw.io 编辑器，支持 XML、CSV、Mermaid 三种输入。启动只需一行：

npx @drawio/mcp

Claude Desktop 的配置加进 claude_desktop_config.json（macOS 路径 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 在 %APPDATA%\Claude\ 下）：

{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@drawio/mcp"]
    }
  }
}

Claude Code 用户更省事，终端一行搞定：

claude mcp add drawio -- npx -y @drawio/mcp

VS Code 里写到工作区 .vscode/mcp.json，注意键名是 servers 不是 mcpServers：

{
  "servers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

写完点服务器条目上方的 Start，弹出信任提示时确认，把 Copilot Chat 切到 Agent 模式，并在输入框的工具配置（扳手图标）里勾选 drawio 工具。

两个进阶选项：自托管 draw.io 的团队给服务器配 DRAWIO_BASE_URL 环境变量指向自己的实例；想跑在自己的机器上，Docker Hub 有现成镜像 jgraph/drawio-mcp，docker run --rm -p 127.0.0.1:3001:3001 jgraph/drawio-mcp 即可，端点为 http://localhost:3001/mcp。

工具一：create_diagram，从 Mermaid 或 XML 到图

App Server 暴露两个工具。create_diagram 接收 xml 或 mermaid 二选一的纯字符串，可选 postLayout（值只有 "elk"）和 direction（"vertical" 默认 / "horizontal"，仅 XML 生效）。Mermaid 侧官方说明支持 26 种图类型，流程图、时序图、类图、ER 图、甘特图、思维导图都在内。

下面是一次真实调用（2026-10-08，直连托管端点复现）。发送的 Mermaid 原文：

flowchart LR
  A[写提示词] --> B{MCP 客户端}
  B -->|create_diagram| C[聊天内嵌渲染]
  B -->|编辑| D[draw.io 编辑器]

服务器返回两部分：一段确认 JSON（含 _buildId 构建标识），以及一个 app.diagrams.net 链接——在支持内嵌渲染的客户端里图直接长在对话中；在不支持的客户端里，把链接丢给浏览器是等价效果：

{"mermaid":"flowchart LR\n  A[写提示词] --> B{MCP 客户端}\n  ...","_buildId":"115ff0b@2026-09-30T15:11:12.987Z"}

If this client doesn't show the diagram inline, open it in the draw.io editor:
https://app.diagrams.net/?pv=0&grid=0#create=%7B%22type%22%3A%22mermaid%22%2C%22compressed%22%3Atrue%2C%22data%22%3A%22bZDNCsIwEISfZo6V...%22%7D

draw.io 编辑器中打开的 Mermaid 流程图

上面那次调用生成的链接在浏览器打开的样子：四个节点、两条分支，标签即 Mermaid 原文

工具二：search_shapes，一万个图形的检索器

画行业图缺图标时，search_shapes 能按关键词搜 draw.io 全部图形库（AWS、Azure、GCP、Cisco、Kubernetes、UML、BPMN 等一万多个），返回可直接塞进 XML 的 style 字符串；内置库没有的还会从 draw.io 图标服务补品牌 logo。参数就两个：query 关键词、limit 条数上限（默认 10，最大 50）。

实测搜 aws lambda，返回的第一条：

[
  {
    "style": "outlineConnect=0;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;shape=mxgraph.aws3.lambda;fillColor=#F58534;gradientColor=none;",
    "w": 77,
    "h": 93,
    "title": "Lambda"
  },
  ...
]

把这段 style 填进 <mxCell> 的 style 属性，配上 search_shapes 给的宽高，就是一个标准 AWS 图标节点。照这个方法拼一张三节点架构图（API Gateway → Lambda → DynamoDB，图标样式分别来自搜索结果），再交给 create_diagram：

<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="api1" value="API Gateway" style="...mxgraph.aws3.api_gateway;fillColor=#D9A741;..." vertex="1" parent="1">
      <mxGeometry x="80" y="120" width="78" height="78" as="geometry"/></mxCell>
    <mxCell id="lam1" value="Lambda" style="...mxgraph.aws3.lambda;fillColor=#F58534;..." vertex="1" parent="1">
      <mxGeometry x="280" y="120" width="77" height="93" as="geometry"/></mxCell>
    <mxCell id="ddb1" value="DynamoDB" style="...mxgraph.aws4.attribute;fillColor=#C925D1;..." vertex="1" parent="1">
      <mxGeometry x="480" y="125" width="78" height="78" as="geometry"/></mxCell>
    <mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="api1" target="lam1">
      <mxGeometry relative="1" as="geometry"/></mxCell>
    <mxCell id="e2" style="edgeStyle=orthogonalEdgeStyle;" edge="1" parent="1" source="lam1" target="ddb1">
      <mxGeometry relative="1" as="geometry"/></mxCell>
  </root>
</mxGraphModel>

AWS 三节点架构图在 draw.io 中渲染

search_shapes 找图标、手拼 XML、create_diagram 渲染：三节点 AWS 无服务器链路

Tool Server 侧的工具集更大：open_drawio_xml、open_drawio_csv、open_drawio_mermaid 分别对应三种输入（都带 lightbox 只读和 dark 模式参数），另有一组 list_pages / get_page / set_page 可以按页读写本地多页 .drawio 文件，改一页不用整个文件重载。

布局自动整理：ELK 与 libavoid 二选一

AI 生成的图经常盒子位置乱。服务器提供两个互相独立的整理通道：postLayout: "elk" 重新排列节点成整齐的分层布局，边也重新走线；routing: "libavoid" 只重走连线、绕开图形，节点位置不动（Tool Server 侧需 1.3.0 以上）。README 明确说二者选一个就好——ELK 自己会走线，再叠 libavoid 是重复劳动。

把前面那张 Mermaid 图加上 postLayout: "elk" 再调一次，效果立竿见影：

ELK 分层布局后的流程图

同一张图加 postLayout:"elk" 后：四层垂直排布，连线全部正交

代价也要知道：ELK 会丢弃你手工摆的坐标，只保留连线拓扑（README 原话是 vertex positions are replaced, only edge topology survives）。精心排过的图想只顺一顺线，用 routing 而不是 postLayout。另外 Mermaid 图本身自带布局，官方说明这类图两个通道都不需要。

照抄就能用的官方示例提示词

README 给了三条示例，接好服务器后原样发给 AI 即可：

Use open_drawio_mermaid to create a sequence diagram showing OAuth2 authentication flow
Use open_drawio_csv to create an org chart: CEO → CTO, CFO; CTO → 3 Engineers
Use open_drawio_xml to create a detailed AWS architecture diagram with VPC, subnets, and security groups

README 还提醒：Claude Desktop 里可能有多种画图途径，想让模型稳定走 draw.io 这条路，在提示词里点名工具名，或者加一条系统指令「总是使用 draw.io MCP 工具来创建图表」。

数据去哪了，以及诚实的限制

图表内容会不会被传到云端，README 的 Data Residency 一节有明确回答：No component sends your diagram to a cloud rasterizer——没有任何组件把你的图发给云端栅格化服务。Tool Server 这条路更彻底，图数据压缩后放在 URL 的 fragment 部分，从不出本机。自托管 Docker 镜像也是无状态的，容器不落盘、日志里没有图表内容。

限制照实列：内嵌渲染依赖宿主支持 MCP Apps，目前 Claude.ai 与 Cursor 2.6+ 可以，VS Code / Copilot、Claude Code、ChatGPT 不行，后两者该走 Tool Server 或插件路线；版本方面，MCP 社区 Registry 在册版本 1.0.3，而 2026-10-08 实测托管端点自报 drawio-mcp-app 1.0.6，托管端点更新快于 Registry 登记，属正常现象，以官方页面为准。