draw.io MCP
使用以下命令将AI编码代理连接到实时draw.io编辑器 drawio-mcp-server.
______________________________________________________________________
对于人类
这有什么作用
当你的AI客户端启动时，它会运行 drawio-mcp-server --editor 通过 npx。这将启动一个本地draw.io编辑器，网址为 http://localhost:3000AI通过WebSocket与该编辑器进行对话，因此它绘制的任何内容都会在您的浏览器中实时显示。无需桌面应用程序，无需浏览器扩展，无需帐户。
AI可以：
- 编辑当前打开的图表 在浏览器中运行（添加形状、边、标签、图层）
- 创建新
.drawio文件 在磁盘上存储您描述的任何内容，然后在编辑器中手动打开它 - 编辑现有
.drawio文件 通过读取和重写XML直接在磁盘上
服务器生命周期
服务器由您的AI客户端启动和停止——您永远不会手动运行它。
当你的AI客户端（OpenCode、Claude Desktop等）启动时，它会读取MCP配置并生成 drawio-mcp-server --editor 作为一个孩子的过程。当你的AI客户端正常退出时，它会杀死该子进程。你不需要在快乐的道路上考虑这一点。
当它变得复杂时：
| 情况 | 发生了什么 |
|---|---|
| AI客户端正常启动 | 服务器自动生成，编辑器可在 localhost:3000 |
| AI客户端正常退出 | 服务器进程被终止，端口3000和3333被释放 |
| AI客户端崩溃或被强制终止 | 服务器进程可能 孤立的 --仍在运行，仍在控制港口 |
| AI客户端在崩溃后重新启动 | 新服务器实例无法绑定到端口3333，静默退出，MCP显示“未连接” |
| 浏览器选项卡已关闭并重新打开 | 选项卡通过WebSocket自动重新连接——无需重新启动 |
| AI客户端在会话中期重新启动 | 浏览器选项卡失去WebSocket连接-- 重新加载选项卡 客户端重新启动后 |
浏览器选项卡不由服务器或AI客户端管理。服务器运行后，您可以手动打开它，它会独立保持打开状态。服务器不知道或不关心浏览器是否已连接，但 如果没有打开浏览器选项卡，MCP工具调用将无限期挂起，因为这些工具会等待一个永远不会到来的WebSocket回复。
保存您的工作： 关系图状态位于浏览器选项卡中。如果服务器重新启动（并且您重新加载了选项卡），则任何未保存的关系图都将被清除。使用 File → Save 或 Ctrl+S 在draw.io编辑器中保存到 .drawio 在重新启动任何操作之前，请先打开文件。
先决条件
- Node.js v20或更高版本 --检查一下
node --version，从安装 如有需要 - 与MCP兼容的AI客户端（此仓库使用OpenCode；Claude Desktop、Claude Code和Zed也可用）
- 浏览器（在以下网址查看实时编辑器
http://localhost:3000)
draw.io编辑器和MCP服务器本身由以下人员自动下载 npx 首次运行-- 你不需要跑 npm install 对于服务器首次运行时，它会获取约50 MB的draw.io静态资产并将其缓存在本地，这就是为什么 timeout 配置中的设置很重要（见下文）。
设置（OpenCode）
- 确保
opencode.json在您的项目根目录中包含：
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"drawio": {
"type": "local",
"command": ["npx", "-y", "drawio-mcp-server", "--editor"],
"enabled": true,
"timeout": 60000
}
}
}这 timeout: 60000 是必需的——在第一次运行时，资产下载可能会超过默认的5秒超时，连接将出现失败。
- 重新启动OpenCode。
- 打开 http://localhost:3000 在您的浏览器中。
- 编辑器应出现，OpenCode中的MCP状态应显示为已连接。
设置（其他客户端）
克劳德桌面版 --编辑 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--editor"]
}
}
}克劳德代码：
claude mcp add-json drawio '{"type":"stdio","command":"npx","args":["-y","drawio-mcp-server","--editor"]}'泽德 --添加到 ~/.config/zed/settings.json:
{
"context_servers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--editor"],
"env": {}
}
}
}你可以要求AI做什么
连接后，浏览器打开：
- *画一条蛇，身体呈S型曲线，眼睛呈分叉状，舌头呈泡泡状，说Hiss*
- *“创建一个包含三个服务和一个数据库的系统架构图”*
- *“添加一个名为“基础架构”的新层，并将数据库形状移动到该层上”*
- *“创建一个名为
auth-flow.drawio带有登录流程图”*
可用MCP工具（形状、边缘、图层、单元格编辑等）的完整列表记录在 drawio mcp服务器工具参考.
故障排除
MCP显示“未连接”
孤儿 drawio-mcp-server 几乎可以肯定，该进程持有端口3333。新实例启动后立即失败 Port 3333 is already in use，并在stdio传输连接之前退出——因此AI客户端永远不会得到响应。
在Windows上修复：
# Find the PID holding port 3333
Get-NetTCPConnection -LocalPort 3333 | Select-Object OwningProcess
# Kill it
Stop-Process -Id
-Force然后重新启动AI客户端。
首次运行超时
服务器在第一次运行时下载约50 MB的draw.io资产。确保 "timeout": 60000 在你的配置中（它在 opencode.json 在这个回购中）。
端口3000或3333已在使用中
使用备用端口：
"command": ["npx", "-y", "drawio-mcp-server", "--editor", "--http-port", "3001", "--extension-port", "3334"]然后打开 http://localhost:3001 相反。
______________________________________________________________________
对于AI代理
您将通过MCP工具帮助用户在实时draw.io编辑器中绘制图表。在绘制任何图形之前，请遵循以下步骤。
1.验证Node.js是否可用
node --version必须为v20或更高版本。如果它没有安装或太旧，告诉用户并停止——其他任何东西都不起作用。
2.询问用户任何npm包的基础在哪里
MCP服务器本身通过以下方式运行 npx 并且不需要本地安装。但是，如果任何任务需要安装额外的Node.js包（脚本、实用程序、变通方法）， 不要跑 npm install 无需首先询问用户应将哪个目录用作包根目录。在错误的目录中安装软件包会创建 node_modules/, package.json，以及 package-lock.json 在意想不到的地方。明确提问：
“如果我需要安装任何Node.js包，我应该使用哪个目录作为项目根目录？”
如果用户有 package.json 已经使用了该目录。如果没有，在继续之前就地点达成一致。
3.验证MCP服务器是否正在运行，浏览器是否打开
您不启动服务器。 人工智能客户端（OpenCode、Claude Desktop等）诞生 drawio-mcp-server --editor 启动时自动启动，退出时自动终止。您唯一关心的是在调用任何工具之前，确认服务器已启动并且浏览器选项卡已连接。
MCP工具通过WebSocket将命令中继到浏览器选项卡 http://localhost:3000。如果没有打开浏览器选项卡，工具调用将 无限期悬挂 --工具端没有超时。这是最常见的混淆来源。
在调用任何工具之前，请与用户确认：
- 添加MCP配置后，AI客户端是否已启动（或重新启动）？
- 是
http://localhost:3000在浏览器选项卡中打开？ - 如果客户端在会话中期重新启动，用户是否 重新加载 浏览器选项卡？（服务器重新启动时，WebSocket连接会断开。）
使用轻量级呼叫验证连接：
drawio_list-layers如果它返回而没有挂起，则WebSocket连接是活动的，您可以继续。如果它挂起，请停止并要求用户在继续之前检查浏览器选项卡。
4.决定绘图方法——询问用户
使用图表有三种方法。在开始之前澄清用户想要什么：
| 方法 | 何时使用 | 如何使用 |
|---|---|---|
| 编辑活动图表 | 用户希望在绘图时实时查看更改 | 使用MCP工具(add-rectangle, add-edge, edit-cell等）直接——更改立即显示在打开的浏览器选项卡中 |
创建新 .drawio 文件 | 用户想要一个单独的图表，他们将手动打开 | 编写一个有效的 .drawio XML文件到磁盘；用户通过将其拖动到编辑器中来打开它 |
编辑现有 .drawio 文件 | 用户指向现有文件 | 读取XML，修改它，写回它；用户在编辑器中重新加载文件 |
5.戈查斯
- 您无法控制服务器生命周期。 不要尝试启动、停止或重新启动
drawio-mcp-server你自己。如果服务器没有运行，请告诉用户重新启动他们的AI客户端。 - 在没有确认的WebSocket连接的情况下，切勿在浏览器中打开编辑器。 如果服务器重新启动，则需要重新加载页面，然后工具调用才能工作。
- 孤立进程。 如果MCP服务器无法启动，请检查之前的实例是否持有端口3000和/或3333（请参阅上文“人工”部分中的故障排除）。
- 不要创造
package.json或node_modules/未经用户同意 --这是在一次失败的解决方法尝试中发生的，必须手动清理。 - MCP工具仅管理活动页面。 没有工具可以在draw.io页面（编辑器底部的选项卡）之间创建或切换。要将内容放在单独的页面上，请创建单独的
.drawio文件。