如何把 Next AI Draw.io MCP Server 接入 Claude Desktop、Cursor 或 Claude Code CLI
如何把 Next AI Draw.io MCP Server 接入 Claude Desktop、Cursor 或 Claude Code CLI
Next AI Draw.io 除了 Web 应用形态外,还发布了一个 MCP(Model Context Protocol)服务器包 @next-ai-drawio/mcp-server,用于把 draw.io 画图能力接进 Claude Desktop、Cursor 或 Claude Code CLI。接入后,你用自然语言描述图表需求,AI 会通过 MCP 工具调用生成图表,并在浏览器里实时预览;整个服务器包是自包含的,内置 HTTP 服务,不需要额外安装外部依赖。本文按这三种客户端分别给出配置路径、配置内容和验证方式。
准备工作
- Node.js 环境:
@next-ai-drawio/mcp-server包声明engines.node为>=18,客户端通过npx拉取并运行该包,所以机器上需要有满足该版本的 Node 和可用的npx。 - 一个支持 MCP 的客户端:Claude Desktop、Cursor 或 Claude Code CLI 三选一。
- 预览界面默认从
https://embed.diagrams.net加载 draw.io UI,因此首次打开浏览器预览时需要联网;私有化部署场景见后文DRAWIO_BASE_URL说明。
Claude Desktop 接入
macOS 上 Claude Desktop 的配置文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json,在其中加入 mcpServers 配置:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["@next-ai-drawio/mcp-server@latest"]
}
}
}
command 固定为 npx,args 指向 npm 包 @next-ai-drawio/mcp-server@latest,这是 MCP Server 文档给出的标准启动方式。保存配置后重启 Claude Desktop。
Cursor 接入
把同样的 mcpServers 配置写入 Cursor 的 MCP 配置文件 ~/.cursor/mcp.json:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["@next-ai-drawio/mcp-server@latest"]
}
}
}
如果你已经在该文件里配置过其他 MCP 服务器,把 drawio 这一项合并进现有 mcpServers 对象即可。保存后重启 Cursor。
Claude Code CLI 接入
Claude Code 使用命令行注册 MCP 服务器,无需手工编辑 JSON:
claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
这条命令注册了一个名为 drawio 的服务器,启动命令为 npx @next-ai-drawio/mcp-server@latest,与上面两种客户端使用的是同一个包。
仓库中还有一个 Claude Code 插件入口(见 packages/claude-plugin/README.md),其中 /plugin install next-ai-drawio 仍标注为 Coming Soon;当前可用的手动方式是 claude --plugin-dir /path/to/packages/claude-plugin,或直接用上面的 claude mcp add 命令注册 MCP 服务器。
验证接入是否生效
按 MCP Server 文档的 Usage 流程验证(三种客户端通用):
-
更新配置后重启 MCP 客户端。
-
让 AI 创建一个图表,例如:
"Create a flowchart showing user authentication with login, MFA, and session management"
-
成功的表现是浏览器自动打开 draw.io 预览窗口,并且图表随着 AI 的生成过程实时更新。
背后发生了什么:AI 会先调用 start_session 工具,服务器启动内置 HTTP 服务(默认端口 6002)并打开浏览器;浏览器 URL 带有 ?mcp= 查询参数,其中的会话 ID 把浏览器和服务器关联起来。服务器提供的工具包括:
| 工具 | 作用 |
|---|---|
start_session |
打开浏览器,开始实时预览会话 |
create_new_diagram |
用 XML 新建图表(需要 xml 参数) |
load_diagram |
从磁盘加载 .drawio 文件到会话(支持压缩文件) |
edit_diagram |
按 ID 操作增删改单元格 |
get_diagram |
获取当前图表 XML |
export_diagram |
导出为 .drawio、.png 或 .svg |
list_pages / add_page / rename_page / delete_page |
多页(多 tab)管理 |
可选:私有化部署(自托管 draw.io)
如果安全要求不允许访问 embed.diagrams.net,可以部署自己的 draw.io 实例,并通过环境变量 DRAWIO_BASE_URL 指过去。MCP Server 文档给出的自托管方式是官方 Docker 镜像:
docker run -d -p 8080:8080 jgraph/drawio
然后在客户端配置中加 env 字段,把 DRAWIO_BASE_URL 设为自托管实例地址:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["@next-ai-drawio/mcp-server@latest"],
"env": {
"DRAWIO_BASE_URL": "https://drawio.your-company.com"
}
}
}
}
文档中的 https://drawio.your-company.com 是占位示例,需替换为你自己的实例地址;用上面的 Docker 命令本地运行时对应 DRAWIO_BASE_URL=http://localhost:8080。Claude Code CLI 场景下则通过 env 变量方式提供该配置(claude mcp add 注册的是同一条启动命令,配置项以各客户端文档为准)。
配置项与常见问题排查
两个环境变量(来自 MCP Server README 的 Configuration 表):
| 变量 | 默认值 | 说明 |
|---|---|---|
PORT |
6002 |
内置 HTTP 服务器端口 |
DRAWIO_BASE_URL |
https://embed.diagrams.net |
draw.io embed 的基础地址,私有部署时改为自托管实例 |
按文档的 Troubleshooting 章节,接入后常见三类问题:
端口 6002 被占用:服务器会自动尝试下一个可用端口,直到 6020 为止;也可以在配置里显式指定端口,例如 "env": { "PORT": "6003" }。
报 "No active session":需要先调用 start_session 打开浏览器窗口;正常让 AI 画图时它会自动先调这个工具,出现该错误说明会话没有建立成功。
浏览器不更新:检查浏览器地址栏 URL 是否带有 ?mcp= 查询参数,会话 ID 是浏览器与服务器之间的连接纽带,参数丢失时更新会断开。
如果三种客户端都配置完成但浏览器始终打不开,可以对照上面三项依次核对:端口是否可用(或是否已被自动递增)、会话是否创建成功、浏览器 URL 是否完整。
完整工具列表与工具行为细节可参考 packages/mcp-server/README.md,Claude Code 插件背景见 packages/claude-plugin/README.md,主 README 的 MCP Server 一节(README.md)也汇总了 Claude Desktop 与 Claude Code CLI 的配置方式。