drawio-mcp-diagramming

Draw.io MCP 绘图技能

通过 Draw.io MCP 服务创建或更新图表。生成 XML 前，请阅读 references/xml-authoring-rules.md——其中的硬性约束、容器规则和边路由指南可避免最常见的渲染故障。有关布局反模式的修复，请参阅 references/layout-antipatterns.md。有关云拓扑约定、图标库和示例，请参阅 references/azure.md、[references/aws.md] (references/aws.md) 和 references/gcp.md。

对于仅使用基本形状的图表（流程图、UML、ERD、组织结构图、思维导图、时间线、线框图），可跳过图标发现，直接调用 drawio/create_diagram 或 drawio/open_drawio_mermaid。

适用场景

• 用户要求创建或优化架构图（Azure、AWS、多云或通用架构）。
• 用户希望通过 MCP 工作流生成 draw.io/diagrams.net 输出。
• 用户要求进行 Mermaid → draw.io 转换。
• 用户要求进行 CSV → draw.io 转换（组织结构图、根据表格数据生成流程图）。
• 用户需要在图表中使用 Azure 服务图标。
• 用户需要在图表中使用 AWS 服务图标。
• 用户报告 Azure 或 AWS 图标/形状未显示。
• 用户要求绘制 身份验证或身份流程（OAuth 2.0、OIDC、JWT 验证、SSO、登录、令牌交换、Entra、Cognito）。
• 用户要求绘制 API 或微服务交互图（请求/响应链、服务间调用、API 网关流程）。
• 用户要求绘制 CI/CD 管道或部署工作流（构建、测试、部署阶段、GitHub Actions、Azure DevOps、审批关卡）。
• 用户希望编辑现有的多页 .drawio 文件（仅限工具服务）。

所需工具

Draw.io 提供两个 MCP 服务变体。此技能适用于两者；请调用与已配置服务相匹配的工具。

选项 A — 托管应用服务（内嵌 /“Open in draw.io”按钮）

• MCP 工具：drawio/create_diagram
• 工作区 MCP 配置：

{
  "servers": {
    "drawio": {
      "type": "http",
      "url": "https://mcp.draw.io/mcp"
    }
  }
}

支持的输入：xml（draw.io XML）、mermaid（Mermaid.js 文本）。 可选布局处理：postLayout: "elk"、routing: "libavoid"。

选项 B — stdio 工具服务（在浏览器中打开 draw.io）

• MCP 工具：drawio/open_drawio_xml、drawio/open_drawio_mermaid、drawio/open_drawio_csv、drawio/search_shapes、drawio/list_pages、drawio/get_page、drawio/set_page
• 工作区 MCP 配置：

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

支持的输入：XML、Mermaid、CSV。 可选布局处理：在 open_drawio_xml 上使用 routing: "libavoid"——需要 @drawio/mcp v1.3.0 或更高版本。在旧版本中，该参数会被忽略；如果连接器路由没有改善，请固定使用 npx -y @drawio/mcp@latest。

如果你的宿主支持 MCP Apps 内嵌渲染（Claude.ai、Cursor ≥ 2.6），或可以接受“Open in draw.io”按钮工作流，请使用选项 A。VS Code / GitHub Copilot 或任何标准 MCP 客户端请使用选项 B。

图标发现工具（两种服务均适用）

• MCP 工具：drawio/search_shapes——搜索 10,000 多种 draw.io 形状，并返回可直接使用的样式字符串。
• 参数：query（以空格分隔的关键词）和可选的 limit（默认值为 10，最大值为 50）。如果首次搜索没有找到可用结果，请先调高 limit，再判断形状是否不存在。

工具名称检测

MCP 宿主可能会为工具注册带有服务前缀的名称（例如 mcp_drawio-mcp-ap_create_diagram 和 mcp_drawio-mcp-ap_search_shapes）。如果 tool_search 没有显示 drawio 工具，请检查可用工具或延迟工具列表，并调用其中显示的确切名称。如果某个工具出现在延迟列表中，不要认为它不可用；请使用已注册的确切名称。

VS Code / GitHub Copilot：依次执行形状搜索

在 VS Code 和 GitHub Copilot 中，如果用户在工具调用执行期间发送新消息，并行工具调用就会被取消。始终一次只运行一个 drawio/search_shapes 调用，切勿并行批量执行。

XML 硬性约束、容器与边缘路由

draw.io MCP 服务强制执行严格的 XML 规则，最常见的质量问题是层级扁平化和手动路由边缘。生成任何 XML 之前，请阅读 references/xml-authoring-rules.md，其中涵盖：

• 硬性约束——会导致服务返回渲染错误的禁止结构（XML 注释、重复 ID、自闭合的边缘/几何元素、未转义字符）
• 容器规则——嵌套 swimlane 的包含关系、子元素的相对坐标，以及跨容器边缘为何必须设置 parent="1"
• 边缘路由——使用 routing: "libavoid" 或 postLayout: "elk" 计算路径；仅在少数合理情况下使用手动连接点
• 生成前边缘检查清单——编写任何基础设施图的边缘 XML 之前先运行

推荐工作流

1. 识别输入格式和图表类型

   • 对于流程图、时序图、ERD、思维导图、甘特图、时间线、看板：如果 Tool Server 可用，优先使用 Mermaid；也可以使用 App Server 的 mermaid 参数。
   • 对于根据表格数据生成的组织结构图或流程图：使用 Tool Server 的 CSV（drawio/open_drawio_csv）。
   • 对于包含命名服务、供应商形状或图示图标的图表：使用 XML（drawio/create_diagram 或 drawio/open_drawio_xml）。

2. 对任何非几何形状使用 drawio/search_shapes——它会搜索所有 draw.io 图形库中的 10,000 多种形状，并返回可直接使用的样式字符串。

   • 用于云服务（Azure、AWS、GCP）、网络设备（Cisco、Juniper）、容器/编排工具（Kubernetes、Docker）、品牌徽标（Slack、GitHub）、IT 基础设施形状以及其他任何命名组件。
   • 查询示例："azure virtual machine"、"aws lambda"、"cisco router"、"kubernetes pod"、"slack"、"docker"。
   • 直接在 XML 单元格中使用返回的样式字符串（硬性门槛和回退流程请参阅下文的「图标发现」）。
   • 仅当图表完全由几何形状构成时才跳过 search_shapes：矩形、菱形、圆形和箭头。

3. 何时使用或跳过 search_shapes——如果形状具有已知名称、品牌或产品标识，务必先通过 search_shapes 查询。只有不需要图示图标的标准几何图表（流程图、UML、ERD、组织结构图、思维导图、时间线、线框图）才可跳过。对于时序图和流程图，请遵循「时序图与流程图模式」（见下文章节）。

4. 使用真实容器嵌套分组，而不是堆叠矩形——对于任何具有层级结构的图表（VNet → Subnet → resource、VPC → AZ → instance、Region → Environment → Service、泳道），请将每一层设为 swimlane;startSize=24; 容器，在子元素上设置 parent="<container_id>"，并为子元素提供相对于其父级的坐标。不同容器中单元格之间的边缘必须使用 parent="1"，否则会渲染在容器内部并被裁切。绘制一个大矩形，再用绝对坐标将形状放在其上方，是 draw.io XML 参考中明确指出的反面模式——这会破坏移动/调整大小、折叠和布局处理。

5. 保持标签唯一且精简——如果多条边的文字相同，请合并为一条带标签的流程或一个注释框。不要在标题、图例、泳道名称和标注中重复相同文字；每个文本元素都应各司其职。

6. 绘制云基础设施图时，加载供应商参考资料 — 对于包含 VNet、子网或 Azure 图标的内容，请阅读 references/azure.md；对于包含 VPC、AZ 或 AWS 图标的内容，请阅读 references/aws.md；对于包含 VPC、区域子网或 GCP 图标的内容，请阅读 references/gcp.md。绘制多云图时，请阅读所有适用的资料。每份资料都介绍了相应供应商的图标库及注意事项、容器结构、配色方案、注释框、完整示例和拓扑检查清单。GCP 的网络模型（全局 VPC、区域子网、VPC 级防火墙规则）与 Azure 或 AWS 的模型并不直接对应；即使你熟悉 Azure/AWS 的惯例，也请阅读 references/gcp.md。

7. 构建载荷

   • XML：有效的 mxGraphModel，使用已验证的图标／样式字符串。
   • Mermaid：有效的 Mermaid.js 定义（App Server：作为 mermaid 传入；Tool Server：使用 drawio/open_drawio_mermaid）。
   • CSV：有效的 CSV 内容（Tool Server：使用 drawio/open_drawio_csv）。

8. 调用相应的工具

   • App Server：使用 xml 或 mermaid 调用 drawio/create_diagram。
   • Tool Server：调用 drawio/open_drawio_xml、drawio/open_drawio_mermaid 或 drawio/open_drawio_csv。

9. 写 XML 前先确定布局方式，然后让它负责布线

   • routing: "libavoid" — 保留手动设置的坐标，只重新规划连接线，使其绕开形状。这是拓扑图、架构图、部署图和基于容器的图表的默认设置。
   • postLayout: "elk" — 完全重新布局，替换顶点位置。用于方向明确／分层的 XML（流水线、决策流程）。流程从左向右时，添加 direction: "horizontal" — 默认值为 vertical，因此从左向右的 CI/CD 流水线会变成上下堆叠。
   • 不要同时使用 postLayout 和 routing — ELK 会自行规划连接线。direction 仅适用于 XML，对 Mermaid 无效（Mermaid 使用 flowchart TD/LR 设置方向）。
   • 不要手动编写 exitX／entryX 或 <Array as="points"> 路径点。布线过程会自动计算这些值，手动设置会与其冲突。少数例外情况请参阅 references/xml-authoring-rules.md。

10. 如果用户需要文件产物，请保存为 .drawio，并用 <mxfile><diagram>...</diagram></mxfile> 包裹。手动编写任何 .drawio 文件前（或 MCP 工具不可用时），请先阅读 references/standalone-file-requirements.md — MCP 工具会自动添加 as="geometry" 和 mxGraphModel 布局属性；没有这些属性，所有元素都会折叠到原点。

11. 标签应简洁明确（服务名称 + 角色）。

12. 每个主要组件或服务优先使用一个图标；使用连接线表示流向语义（入口／出口／依赖／遥测）。

输入格式速查

选择与图表类型和已配置服务相匹配的输入。

输入	最适用场景	App Server	Tool Server
XML	使用供应商图标或图形化图标、自定义布局的架构／拓扑图	使用 xml 调用 drawio/create_diagram	drawio/open_drawio_xml
Mermaid	流程图、时序图、类图、ER 图、状态图、思维导图、甘特图、时间线、看板	使用 mermaid 调用 drawio/create_diagram	drawio/open_drawio_mermaid
CSV	组织结构图、流程图、根据表格数据生成的简单图表	不支持	drawio/open_drawio_csv

对于标准图表类型，请使用 Mermaid；如果用户需要图形化或特定供应商的图标、精确定位、复杂容器或自定义样式，请使用 XML。Mermaid/CSV 示例和多页编辑详情请参阅 references/REFERENCE.md。

视觉质量规范

除非用户明确要求密集或技术性视图，否则请遵循以下默认规则：

• 最多使用 3-4 个主要泳道/区域（例如：源 → 处理 → 目标）。
• 主要流程应从左向右，并保持一条主路径。
• 使用阶段编号（1、2、3、4），而不是大量边标签。
• 每个主要组件使用一个图标；避免每个步骤都配图标。
• 跨泳道的虚线最多保留一条安全/身份验证线和一条可选的遥测线。
• 边的密度：对于有 3 条或更多出边的节点，先减少重复项（例如，将一个网关到一个汇总后端的边合并）。然后让 routing: "libavoid" 分隔剩余边——只有在路由后某条特定边仍不明确时，才添加显式的 exitX/exitY。
• 文本应简洁（每个框只表达一个用途），避免多行内容过多。
• 边标签应简短且各不相同；如果相邻边重复使用相同的协议/端口描述，应将其合并，或把共用详情移至一个注释框中。
• 避免在标题、图例、泳道名称和标注中重复相同的标签。
• 连接线上的流动动画：在任意边样式中添加 flowAnimation=1;，即可渲染沿箭头移动的圆点，让流向一目了然，无需额外标签——特别适合数据流和流水线图。导出为 SVG 和使用 draw.io 桌面应用时，动画都会保留。默认情况下，在生成图表前询问用户是否要为任何流向箭头添加动画——"您希望为哪些流向箭头添加动画以显示流量方向？" 仅对用户指定的边应用 flowAnimation=1;。如果用户已表示希望图表保持静态/简洁，则跳过此问题。
• 优先提供“简洁”版本；仅在用户要求时添加细节。

有关常见布局问题（边堆叠、标签重复、VNet 内的可观测性等）的示例，请参阅 references/layout-antipatterns.md。

云基础设施拓扑（Azure、AWS 和 GCP）

各云厂商的专属拓扑指南位于对应的参考文件中。请加载与图表匹配的文件；多云图表则加载多个文件：

• Azure — references/azure.md：对于包含 VNet、子网或 Azure 图标的图表，请阅读此文件。内容涵盖 azure2 和 mscae 图标库及其注意事项、嵌套的 VNet → 子网容器结构、颜色和边框规范、流量配色、注释框、完整示例，以及 Azure 拓扑检查清单。
• AWS — references/aws.md：对于包含 VPC、AZ 或 AWS 图标的图表，请阅读此文件。内容涵盖 AWS4 模板库及其注意事项、嵌套的 VPC → AZ → 子网容器结构、子网层级配色、NAT/IGW 出站路径、安全组注释、完整示例，以及 AWS 拓扑检查清单。
• GCP — references/gcp.md：对于包含 VPC、区域子网或 GCP 图标的图表，请阅读此文件。内容涵盖 gcp2 模板库及其注意事项、全局 VPC/区域子网容器模型（并非 Azure 或 AWS 模型的直接对应形式）、VPC 级别的防火墙规则注释、完整示例，以及 GCP 拓扑检查清单。

适用于这三者的通用规则——包含关系、边路由和严格的 XML 约束——请参阅 references/xml-authoring-rules.md。

序列图和流程图模式

本节适用于展示时间流程（即事件发生的顺序）的图表，而非基础设施拓扑图。无需通过 drawio/search_shapes 查找形状。

适用场景

图表类型	关键词	布局
身份验证／授权流程	OAuth、OIDC、JWT、SSO、登录、令牌交换、Entra、Cognito	泳道交互流程
API／微服务调用链	REST、GraphQL、请求／响应、服务间调用、API 网关	泳道或纵向流程图
CI/CD 流水线	流水线、构建、部署、发布、GitHub Actions、Azure DevOps、审批关卡	横向流程图

布局方法

泳道交互流程（包含 2–5 个参与者的身份验证／API 流程）：

• 在 parent="1" 下，将扁平的 swimlane 泳道垂直堆叠，每个泳道对应一个参与者：swimlane;horizontal=0;startSize=110;fillColor=<pastel>;html=1;，几何参数为 x=0, y=lane_index*150, width=CANVAS_W, height=150
• 步骤框作为泳道的子元素（parent="<lane_id>"），坐标相对于泳道：x = 120 + col*180、y = 45，尺寸为 140x60（决策菱形为 140x80）。起始位置 x=120 可避开 110px 的标题区域
• 在标签中为步骤编号（1.、2.、3.），以明确执行顺序
• 跨泳道边必须位于 parent="1" 下，而非泳道内，否则会被裁切
• 使用 edgeStyle=orthogonalEdgeStyle;，并由路由处理阶段设置折点
• 画布宽度：max_col * 180 + 300；不要将泳道嵌套在池中，也不要改变泳道高度
• 画布高度：actor_count * 150 + 100

横向流水线流程图（CI/CD）：

• 阶段从左向右流动：Source → Build → Test → Staging → Approval → Production
• 阶段使用 rounded=1 矩形，关卡／决策点使用 rhombus 形状
• 根据下方的阶段颜色表为各阶段框设置颜色
• 失败分支从关卡向下延伸，并使用红色边连接到 Rollback/Notify 步骤
• 传入 postLayout: "elk" 和 direction: "horizontal"——若不指定 direction，默认的纵向布局会将流水线从上到下堆叠
• 画布：pageWidth="1700" pageHeight="600"

颜色规范

边的颜色（与拓扑图配色保持一致）：

含义	strokeColor	样式
主请求／调用	#0078D4 Azure 蓝	实线，strokeWidth=2
成功响应／返回	#00897B Teal	实线，strokeWidth=2
令牌／凭据／重定向	#F57C00 Amber	dashed=1、strokeWidth=2
异步／事件驱动调用	#5C6BC0 Indigo	dashed=1、strokeWidth=2
错误／拒绝／回滚	#C62828 Red	实线，strokeWidth=2
可选／有条件	#666666 Grey	dashed=1、strokeWidth=1

参与者泳道颜色（泳道标题＋列背景，opacity=30）：

参与者类型	fillColor	strokeColor
用户／浏览器／客户端	#dae8fc	#6c8ebf
身份提供商（Entra、Cognito、Okta）	#e6f4ea	#82b366
API／后端服务	#fff3e0	#e6821e
数据库／数据存储	#f5f5f5	#666666
托管服务／外部系统	#f3e5f5	#7B1FA2

阶段填充颜色（CI/CD 流水线）：

阶段	fillColor	fontColor
Source / Trigger	#0078D4	#ffffff
Build	#00897B	#ffffff
Test / Quality Gate	#F57C00	#ffffff
Deploy to Staging	#5C6BC0	#ffffff
Approval Gate	#795548	#ffffff
Deploy to Production	#43A047	#ffffff
Rollback / Failure	#C62828	#ffffff

流程动画

flowAnimation=1; 可像在拓扑图中一样用于序列／流程边。应用于主要调用路径或流水线阶段转换。应用前务必先征求用户同意。

检查清单（序列／流程图）

• 已确认图表类型（身份验证流程／API 流程／CI/CD 流水线）
• 已清晰标注参与者
• 已按执行顺序为步骤编号
• 边的颜色符合上述规范
• 错误／失败路径已用红色标出
• 生成前已向用户确认是否需要动画
• 画布尺寸适合参与者数量和步骤深度

图标发现

对于任何带有名称、品牌或产品标识的形状（云服务、网络设备、品牌徽标、容器／编排工具或任何其他图示图标），drawio/search_shapes 是样式字符串的唯一可接受来源。绝不要猜测或编造；本规则在此技能的其他位置引用，不再重复说明。

按类别划分的示例查询：

类别	示例查询
Azure	"azure virtual machine"、"azure key vault"、"azure api management"
AWS	"aws lambda"、"aws s3"、"aws ec2"
GCP	"gcp compute engine"、"gcp cloud storage"
网络设备	"cisco router"、"cisco firewall"、"juniper switch"
容器／编排	"kubernetes pod"、"docker"、"helm"
品牌／SaaS	"slack"、"github"、"jira"、"salesforce"
本地部署／IT	"server"、"database"、"laptop"、"printer"

始终将返回的 style 值直接用于 mxCell。样式格式因库而异：

# Image-based (Azure azure2, SVG files)
image;aspect=fixed;html=1;points=[];align=center;image=img/lib/azure2/<category>/<Name>.svg;

# Stencil-based (AWS4, GCP2, shape libraries)
shape=mxgraph.aws4.<name>;fillColor=<color>;fontColor=#ffffff;strokeColor=none;

# Stencil-based (Cisco, Kubernetes, etc.)
shape=mxgraph.cisco.<category>.<name>;sketch=0;html=1;

# Icon-service (brand logos and concept icons, returned as an absolute URL)
shape=image;html=1;verticalLabelPosition=bottom;verticalAlign=top;image=https://<icon-service-host>/<icon>.svg;

当内置库中没有合适的匹配项时，search_shapes 会从 draw.io 图标服务（与编辑器侧边栏使用的分组图标搜索相同）补充搜索结果，并以带绝对 URL 的 shape=image 样式返回。这些都是有效结果——应按返回值使用，不要因为它们不符合 img/lib/... 路径格式而拒绝。

如果样式字符串无法确认，或形状渲染不正确：

1. 重新查询 search_shapes（将 limit 提高到最多 50）以寻找替代项——不要在一次范围过窄的查询后就断定某个形状不存在。
2. 不要使用尚未解决的形状样式生成图表。
3. 如果有多个形状尚未解决，请列出它们，并在生成任何内容之前提出已验证的替代项。
4. 确认所有替代项后，再生成图表。

导出图表

格式	操作方法	备注
SVG	File → Export As → SVG	推荐——可保留 flowAnimation 移动点效果和所有图标渲染。用于分享或嵌入。
PNG	File → Export As → PNG	静态快照。不会捕获 flowAnimation 效果；会保留图标和颜色。
PDF	File → Export As → PDF	最适合打印或嵌入文档的图表。仅静态。
.drawio file	File → Save As	保留所有 XML、动画设置和样式属性，方便日后编辑。

flowAnimation=1 仅在图表于 draw.io 桌面版中打开或渲染为 SVG 时可见。PNG 或 PDF 导出中不会显示——如果用户询问动画为何没有显示，请告知他们这一点。

故障排查清单

• 确认已配置的 MCP 服务显示在 MCP: List Servers 中。
• 如果工具列表已过期，请运行 MCP: Reset Cached Tools。
• 禁止使用 XML 注释（``）——MCP 服务会拒绝它们。提交前请删除所有注释。
• 确保 XML 其他部分格式正确（没有格式错误的标签、重复的 ID，或样式字符串中未经转义的 </>/&）。
• Z 顺序：当形状是 parent="1" 的同级元素时，背景矩形必须定义在其后方图标之前，否则背景矩形会渲染在图标上方。使用真实容器（swimlane、container=1）可完全避免这个问题——子元素始终渲染在父元素上方。
• 对于 value 中包含 HTML 标签（<b>、<br>、<i>）的任何单元格，样式中都必须包含 html=1。换行符 
 无需此设置即可生效。
• 搜索结果中的 sketch=0：如果 drawio/search_shapes 返回的样式字符串包含 sketch=0，请原样保留——省略它会启用该形状的手绘草图渲染模式。
• 图标尺寸：使用 search_shapes 返回的尺寸；这些尺寸反映了预期的宽高比。为保持一行图标在视觉上的一致性而统一尺寸时，64×64 是稳妥的通用尺寸。对于样式中带有 aspect=fixed 的图标，切勿更改其宽高比。
• Azure / AWS / GCP 图标渲染：特定供应商的样式规则和修复方法见 references/azure.md、references/aws.md 和 references/gcp.md。
• 如果 VS Code 扩展的渲染结果不同，请在网页版 draw.io 中重新打开图表。
• 如果图标显示不正确，请使用 drawio/search_shapes 查找其他精确的样式字符串。

提示词模板和清单

图表类型的提示词预设见 references/REFERENCE.md，布局预检清单见 references/layout-antipatterns.md。

完成标准

• 已选择正确的输入格式和 MCP 工具（XML、Mermaid 或 CSV；App Server 或 Tool Server）。
• 生成前已通过 drawio/search_shapes 确认所有图标/样式字符串；未确认的图标不得使用。
• 图表渲染正确；XML/Mermaid/CSV 格式有效，且可在 draw.io 中打开。
• 所有命名组件均可通过正确的图标和清晰的标签识别。
• 已有意选择布局流程（手动放置/容器布局使用 routing: "libavoid"；方向性图表使用 postLayout: "elk"——从左到右的流程需设置 direction: "horizontal"；两者不得同时使用）。
• 已通过所有适用的拓扑清单项（边框、子网、流量标签、图例、隔离框、区域、画布尺寸）。
• 已通过所有适用的序列/流程清单项（编号步骤、按颜色区分的边、错误路径、画布尺寸）。
• 已确认动画偏好；仅对用户指定的边应用 flowAnimation=1;。
• 嵌套分组使用真实容器：每一层都是一个 swimlane，子元素以相对坐标作为其容器的子元素，跨容器的边使用 parent="1"。
• 如有要求，文件产物保存为 .drawio（用 <mxfile> 包裹），并遵循 references/standalone-file-requirements.md。
• 边仅声明 source/target：除非适用已记录的例外，否则不得手写 <Array as="points"> 路径点或 exitX/entryX 覆盖项。见 references/xml-authoring-rules.md。
• 定稿前，已对照 references/layout-antipatterns.md 检查布局反模式。