Diagrams.so

@diagrams-so/mcp

Diagrams.so MCP 服务 — 可通过任意 MCP 客户端（Claude Desktop、Claude Code、Cursor）生成、编辑和管理云架构图。这是一个基于 stdio 的轻量客户端，调用公开的 Diagrams.so API（/api/v2）；每个工具对应一次 REST 调用。

快速开始

需要 Node ≥ 18。无需复制 API 密钥：在浏览器中批准即可连接。

# 1. add the server to Claude Code
claude mcp add diagrams-so -- npx -y @diagrams-so/mcp

# 2. connect this machine (a browser opens, press Approve)
npx @diagrams-so/mcp login

重启客户端，然后询问：“生成一个 AWS 三层 Web 应用架构图，并告诉我有哪些警告。” 如果想先确认 23 个工具都已注册，请运行 /mcp。

经常使用？安装一次，之后命令会更短：

npm i -g @diagrams-so/mcp
diagrams-so login

默认情况下，该服务连接到生产环境（https://api.diagrams.so/api/v2）。如需连接本地或 可自托管的 API，请设置 DIAGRAMS_API_BASE。

使用 Claude Desktop 或 Cursor，而不是 CLI？请参阅将其添加到 MCP 客户端。希望一键安装、无需终端操作？请参阅一键安装（MCPB）。

完全不使用终端（Claude Desktop）

将此服务添加到客户端配置（如下），并设置 DIAGRAMS_LOGIN_EMAIL 为你的电子邮箱， 然后直接请求生成架构图。由于这台设备尚未连接，首次调用工具时，系统会通过电子邮件 发送一次性登录码，并回复一个链接。打开链接，输入验证码，点击 批准，然后再次提出请求。无需安装或输入任何命令。

在 Claude 中生成架构图

login 只负责连接设备，不会自行生成任何内容，因此无需在终端中输入 generate 命令。你只需在助手的常规聊天框中输入提示词，助手便会为你调用工具。

客户端	输入提示词的位置
Claude Code	终端聊天界面，也就是你提出其他问题的位置
Claude Desktop	常规消息框
Cursor	聊天或编辑面板

MCP 服务会在启动时加载，因此添加服务后请重启客户端。 然后运行 /mcp，并 确认 diagrams-so 显示 23 个工具。

现在只需用日常语言提出请求：

生成一个 AWS 三层 Web 应用，包含 ALB、EC2 Auto Scaling 和 RDS Multi-AZ。 显示设计警告，然后将其导出为 draw.io 格式。

收到这句话后，助手会依次调用 generate_diagram、get_warnings 和 export_diagram。你无需指定工具或编写 JSON。

生成架构图后，还可以尝试这样提问：

警告提到传输过程中没有加密。请修复这一项，并告诉我新评分。

在 ALB 前面添加一个 CloudFront 分发。

重新导出为 SVG，这样我就可以把它放进 README 里。

所有方案都支持无限量的架构图和编辑。没有按量计费；只有每分钟请求速率限制。付费方案无水印，并支持 draw.io 导出。免费方案的架构图可以设为私有。

使用付费方案时，助手保存的 .drawio 文件可在 app.diagrams.net 或桌面应用中打开并完整编辑：它是真正的 draw.io XML 文件，而不是图片。免费方案的 工具则会返回带水印的图片（SVG），并说明这一点；要获取可编辑的 draw.io 文件，需使用付费方案。

不想使用助手？ diagrams.so/create 提供相同功能的网页：只需在框中输入提示词。无需安装、无需 login，也无需 MCP。

工具（23）

创建与更改（会修改数据）

工具	功能
generate_diagram	根据提示词创建图表 → id + 警告 + 评分 + draw.io XML（付费版）或带水印的图片链接（免费版）
edit_diagram	应用自然语言更改（创建新版本）
fix_warning	解决一项 Well-Architected 警告
relayout_diagram	由 AI 重新排列布局（异步；要求 confirm=true）
import_diagram	将现有 draw.io XML 导入为新图表
update_diagram	重命名 / 更改可见性 / 替换 XML
revert_diagram	恢复到较早的版本
delete_diagram	软删除图表（破坏性操作）
fork_template	将公共 / 库中的图表复制到你的帐户（私有）

读取

工具	功能
get_diagram	获取图表的评分 + XML（付费版）或带水印的图片链接（免费版）
list_diagrams	列出你的图表（游标分页）
get_warnings	获取图表的 Well-Architected 检查结果
export_diagram	原始 svg（所有套餐均可用；免费版带水印）或 drawio（付费版；免费版会提供带水印的 SVG）
list_versions	版本历史（含 is_current）
get_version	获取指定版本的评分 + XML（付费版）或带水印的图片链接（免费版）
get_relayout_status	轮询异步重新布局任务
search_gallery	搜索公共社区和精选库中的图表
enhance_prompt	将粗略想法转化为详细提示词
clarify_prompt	针对含糊的提示词获取澄清问题
get_usage	查看你的套餐和用量
get_usage_history	查看过往任务（操作、图表、界面），支持筛选并显示实时会话统计
whoami	查看帐户、套餐、权限范围以及实时 / 测试模式
list_capabilities	查看有效的图表类型 / 提供方 / 导出格式

所有套餐中的每种工具均不受使用次数限制。delete 是破坏性操作；relayout 在替换布局前会要求设置 confirm=true。

CLI

命令

安装此软件包后，diagrams-so 会添加到你的 PATH 中。较长的 diagrams-so-mcp 名称仍然有效；无需安装任何内容也可运行 npx @diagrams-so/mcp <command>。

npm i -g @diagrams-so/mcp

diagrams-so login          # connect this machine (a browser opens, press Approve)
diagrams-so whoami         # which account is this machine connected as
diagrams-so logout         # remove the local credential
diagrams-so install        # print client config to paste

环境

变量	必需	默认值
DIAGRAMS_API_KEY	❌	—（仅用于 CI 和无头环境；通常使用 login）
DIAGRAMS_API_BASE	❌	https://api.diagrams.so/api/v2（生产环境；可覆盖以用于本地 / 可自托管环境）
DIAGRAMS_API_TIMEOUT_MS	❌	450000（单次请求的安全超时；高于 API 完整的服务端超时阶梯）
DIAGRAMS_BROWSER	❌	—（login 会打开默认浏览器；如果 Diagrams.so 会话位于非默认浏览器中，可设置为例如 Google Chrome）
DIAGRAMS_NO_BROWSER	❌	—（设置为任意值即可阻止 login 打开浏览器；始终会打印 URL）
DIAGRAMS_NO_AUTO_LOGIN	❌	—（设置为任意值即可禁用工具内连接；之后，未验证身份的工具只会提示运行 login）
DIAGRAMS_LOGIN_EMAIL	❌	—（用于工具内连接的地址：一次性登录代码会发送到此邮箱；未设置时，未验证身份的工具会提示运行 login，而不会启动连接流程）

将其添加到 MCP 客户端

已发布的软件包可直接通过 npm 运行，因此无需填写路径，也无需在配置中添加密钥。运行 npx @diagrams-so/mcp install，即可打印适用于你的客户端的配置块。

Claude Code（CLI）

claude mcp add diagrams-so -- npx -y @diagrams-so/mcp
npx @diagrams-so/mcp login

Claude Desktop / Cursor（claude_desktop_config.json / mcp.json）

{
  "mcpServers": {
    "diagrams-so": {
      "command": "npx",
      "args": ["-y", "@diagrams-so/mcp"]
      // optional: "env": { "DIAGRAMS_API_BASE": "http://localhost:8000/api/v2" } for a local API
    }
  }
}

你可以运行一次 npx @diagrams-so/mcp login 来连接；也可以设置 DIAGRAMS_LOGIN_EMAIL，然后请求生成图表，并按照首次工具调用提供的链接操作（登录代码会通过电子邮件发送）。只有在无法打开浏览器的 CI 和无头机器上，才应设置 DIAGRAMS_API_KEY。

重启客户端，然后提出请求：“生成一张 AWS 三层 Web 应用图表，并告诉我有哪些警告。”

一键安装（MCPB）

从最新版本下载 diagrams-so.mcpb，然后将其拖到 Claude Desktop 中。无需终端，也不会再要求 API 密钥：安装后，在首次使用时，点击第一次工具调用提供的链接即可连接。

自行构建安装包是贡献者的步骤，参见本地开发。

Smithery

该服务已列在 smithery.ai/servers/diagrams-so/mcp， 可为你安装，并列出全部 23 个工具及其参数：

npx -y smithery mcp add diagrams-so/mcp

使用相同的安装包和相同的 login 步骤。Smithery 安装的是 MCPB 安装包，而不是 npm 包，因此那里显示的版本会随发布更新，而不是依据 npm dist-tags。

验证其是否正常运行

DIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs

运行完整流程（连接 → 列出工具 → whoami → 生成 → 警告 → 修复 → 导出 → 错误处理）。

持续集成与发布

工作流	触发条件	作用
CI（ci.yml）	每次推送 / PR	在 Node 18/20/22 上运行 npm ci + npm run build，然后执行免费的 smoke 测试（scripts/ci-smoke.mjs），启动构建后的服务并断言所有 23 个工具均已注册。不会调用 API。
Live smoke（live-smoke.yml）	每晚 + 手动	使用真实 API 运行完整端到端流程（test-smoke.mjs）。会调用真实 API，因此仅在设置了 DIAGRAMS_API_KEY 密钥时运行。
Release（release.yml）	标签 vX.Y.Z	构建 → npm prune --omit=dev → 打包 diagrams-so.mcpb → 附加到 GitHub Release。如果设置了 NPM_TOKEN 密钥，也会发布到 npm。

创建一个发布版本：

# bump "version" in package.json + manifest.json to match, commit, then:
git tag v1.2.0 && git push origin v1.2.0

标签必须与 package.json 中的 version 一致（工作流会强制校验）。.mcpb 安装包会显示在 GitHub Release 中；手动运行 workflow_dispatch 会生成可下载的构建产物，但不会发布（便于测试安装包）。

仓库密钥 / 变量（可选）：DIAGRAMS_API_KEY（live smoke）、NPM_TOKEN（发布到 npm）、DIAGRAMS_API_BASE 变量（非生产环境的 live-smoke 目标）。

说明

• stdout 是 MCP 通道——服务仅将日志写入 stderr。
• 错误会作为清晰的 MCP 工具错误返回，其中包含 API 的 code、HTTP 状态和 request_id。
• 服务不会与内部服务或数据库通信，只会访问公开的 /api/v2。
• **长时间运行的工具会在客户端超时后继续运行。**运行期间，generate / edit / fix / relayout / enhance_prompt / clarify_prompt 每 10 秒发送一次 notifications/progress，因此会在收到进度时重置请求超时（resetTimeoutOnProgress）的 MCP 客户端不会因 SDK 默认的 60 秒超时而中止耗时较长的生成任务。如果你的客户端不会在收到进度时重置超时，请提高这些工具的单次调用超时。

本地开发

仅在需要修改服务本身时才需要。用户应从 npm 安装，参见 快速开始。

git clone https://github.com/RedHold/diagrams-mcp-app-core.git
cd diagrams-mcp-app-core
npm install                  # installs deps and builds dist/ via the prepare hook
node scripts/ci-smoke.mjs    # all 23 tools register; no API calls

# point a client at your working copy
claude mcp add diagrams-so-dev -- node "$(pwd)/dist/index.js"

# build the MCPB bundle
npm run build && npx @anthropic-ai/mcpb pack

许可与法律声明

• 代码：Apache-2.0。请参阅 NOTICE。
• **服务：**此服务是 Diagrams.so API 的客户端。API 的使用受 服务条款 和 可接受使用政策 约束；代码许可证不授予任何 API 本身的权利。
• **隐私：**此服务在本地运行，只连接到 api.diagrams.so，且不包含任何遥测功能。login 使用的凭据存储在 ~/.diagrams-so/credentials.json 中，权限仅限所有者访问。请参阅隐私政策。
• **套餐：**每种套餐均提供无限量的图表和编辑次数，并设有每分钟速率限制。付费套餐不添加水印，并支持导出为 draw.io 格式；免费套餐的图表可以设为私有。测试模式密钥会对你的真实账户执行操作。
• **商标：**Diagrams.so 和 Diagrams.so 徽标是 RedHold LLC 的商标。除准确说明此软件包的来源外，此许可证不授予使用这些商标的权限。请参阅商标政策。
• **安全：**请按照 SECURITY.md 中的说明，将漏洞报告发送至 [email protected]。