把你的 AI 接入 DiagramZu

接上 Claude、Cursor 或任意 MCP 客户端，便能从智能体直接驱动你的图表——核心概念、三步快速上手，以及完整的工具与 REST 参考。

第一次用 DiagramZu?先从五个核心概念开始 →

本页内容

快速开始

三步让你的 AI 与 DiagramZu 对话。

STEP 01

注册

创建你的空间并邀请队友。

STEP 02

创建 API 令牌

打开 /app/settings/tokens 创建一个令牌。复制后立即保存 — 之后不会再显示。

STEP 03

添加到 AI 工具

把下方的配置粘贴到你的 Claude / Cursor / ChatGPT 配置中。

MCP 设置

DiagramZu 通过 HTTP 传输公开 14 个工具——跨图表、文件夹、版本历史、幻灯片组与评论的读取、写入和分析原语。安装一次，你的智能体就能直接使用。

一键连接 — Claude

在 Claude 中打开设置 → 连接器 → 添加自定义连接器，粘贴 https://mcp.diagramzu.ai/mcp，并用你的 DiagramZu 账户授权。无需复制 API 令牌。

使用 Cursor、ChatGPT、脚本或其他 MCP 客户端？请使用下方的 API 令牌设置 — 适用于所有客户端。

安装

登录后，令牌会自动填入下方代码片段。

Claude Code

在终端中运行下面的命令，将 dz_live_xxx 替换为你的 API 令牌。

Bash

claude mcp add --scope user --transport http diagramzu https://mcp.diagramzu.ai/mcp \
  --header "Authorization: Bearer dz_live_xxx"

Claude Desktop

编辑 Claude 配置文件(macOS:~/Library/Application Support/Claude/claude_desktop_config.json,Windows:%APPDATA%\Claude\claude_desktop_config.json),然后重启应用。

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json,然后重启 Cursor。

JSON

{
  "mcpServers": {
    "diagramzu": {
      "type": "http",
      "url": "https://mcp.diagramzu.ai/mcp",
      "headers": {
        "Authorization": "Bearer dz_live_xxx"
      }
    }
  }
}

工具参考

读取工具

list_diagrams

查找 Space 中的图表。

使用时机在 create_diagram 之前调用以避免与同名图表重复,或在之后调用以找到最新匹配。

示例

{
  "query": "DB schema",
  "sortBy": "updatedAt",
  "sortDir": "desc"
}

list_folders

列出 Space 中的文件夹。

使用时机当你可能把新图表放到某个特定位置时调用。如果存在名为「Infra」或「Schema」的文件夹,优先放在那里而非根目录。

示例

{}

get_diagram

按 id 获取一个图表,包括描述。

使用时机决定要改什么之前,把描述当作简介阅读。

示例

{
  "id": "dgm_abc123"
}

list_versions

按从新到旧列出图表的手动快照。

使用时机在有风险的覆盖之前使用,以了解有哪些恢复点。

示例

{
  "diagramId": "dgm_abc123"
}

get_version

获取图表的一个历史版本。

使用时机读取过去的快照以理解图表的演变,或恢复当前版本不再具有的内容。

示例

{
  "diagramId": "dgm_abc123",
  "versionId": "ver_xyz789"
}

写入工具

create_diagram

在 Space 中创建图表。

使用时机始终先写描述 —— 它将成为未来调用的智能体简介。设置 folderId 把图表归入由人类管理的文件夹。

示例

{
  "title": "User signup flow",
  "description": "Auth path from /signup → verify → first login.",
  "code": "graph TD; A-->B-->C",
  "folderId": "fld_..."
}

update_diagram

更新现有图表的标题、描述、代码或 styleOptions。

使用时机改动有意义时传 createVersion: true —— 未来的你会想要一个恢复点。versionLabel 会在历史抽屉中显示。

示例

{
  "id": "dgm_abc123",
  "code": "graph LR; A-->B-->C-->D",
  "createVersion": true,
  "versionLabel": "added retry path"
}

分析

analyze_diagram

返回图表的结构性评述 —— 孤立节点、高度数枢纽、循环、断开的连通分量。

使用时机在简化复杂图表之前使用,或作为对生成代码所产生的图是否干净的合理性检查。

示例

{
  "id": "dgm_abc123"
}

幻灯片组

list_decks

列出空间内的演示幻灯片组，按最近编辑排序。

使用时机在 create_deck 之前调用，优先扩展已有幻灯片组而非重复创建。

示例

{}

get_deck

按 id 获取单个幻灯片组及其有序幻灯片。

使用时机在用 update_deck 重排或新增幻灯片前，先读取幻灯片顺序与标题。

示例

{
  "id": "dck_abc123"
}

create_deck

把已有图表组装成有序的幻灯片组。

使用时机先创建各页图表并收集其 id，再按演示顺序传入。返回可分享的演示 URL。

示例

{
  "title": "System architecture walkthrough",
  "description": "Read in order: context → data flow → deploy.",
  "slides": ["dgm_context", "dgm_dataflow", "dgm_deploy"]
}

update_deck

修改幻灯片组的标题、描述或幻灯片顺序。

使用时机 slides 是声明式的——发送期望的完整图表 id 列表；省略的 id 会被移除，新 id 追加在末尾。

示例

{
  "id": "dck_abc123",
  "slides": ["dgm_context", "dgm_dataflow", "dgm_deploy", "dgm_appendix"]
}

list_comments

列出图表上的评论，按时间从旧到新。

使用时机传入 nodeId 只读取某个节点的讨论串；除非设置 includeResolved: false，否则包含已解决的讨论串。

示例

{
  "diagramId": "dgm_abc123",
  "includeResolved": false
}

add_comment

在图表上发表评论，可选择固定到某个节点。

使用时机留下人会在图上看到的结构化评审意见。用 nodeId 固定到节点，或用 parentId 回复讨论串。

示例

{
  "diagramId": "dgm_abc123",
  "nodeId": "PaymentService",
  "body": "This should call the retry queue, not the DB directly."
}

REST API

每个请求都使用 Bearer 令牌认证。基础地址是 https://diagramzu.ai。请将 $SPACE_ID 替换成你的空间 ID(在 app 内的 URL 中可见)。

接口列表

curl · 列表

# List diagrams in your Space
curl -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · 创建

# Create a new diagram
curl -X POST -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My diagram","code":"graph TD; A-->B"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams

curl · 更新

# Update a diagram
curl -X PATCH -H "Authorization: Bearer $DIAGRAMZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"graph LR; A-->B-->C"}' \
  https://diagramzu.ai/api/spaces/$SPACE_ID/diagrams/<DIAGRAM_ID>

DIAGRAMS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams`	List diagrams. Same filters as list_diagrams.
POST	`/api/spaces/[spaceId]/diagrams`	Create a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]`	Fetch one diagram.
PATCH	`/api/spaces/[spaceId]/diagrams/[id]`	Update title, code, description, or styleOptions.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]`	Delete a diagram.
GET	`/api/spaces/[spaceId]/diagrams/[id]/thumbnail`	Rendered thumbnail.
GET	`/api/spaces/[spaceId]/diagrams/[id]/analysis`	Structural analysis (same as analyze_diagram).
GET	`/api/spaces/[spaceId]/diagrams/[id]/embed-stats`	Embed load count for the active share (last 7 days).
POST	`/api/spaces/[spaceId]/diagrams/export/png`	Render arbitrary Mermaid code to PNG.

FOLDERS

Method	Path	Description
GET	`/api/spaces/[spaceId]/folders`	List folders.
POST	`/api/spaces/[spaceId]/folders`	Create a folder.
PATCH	`/api/spaces/[spaceId]/folders/[id]`	Rename or reparent a folder.
DELETE	`/api/spaces/[spaceId]/folders/[id]`	Delete a folder.

VERSIONS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions`	List versions, newest first.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions`	Snapshot the current state.
GET	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]`	Fetch one version.
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/restore`	Restore a version (auto-snapshots first).
POST	`/api/spaces/[spaceId]/diagrams/[id]/versions/[vid]/fork`	Fork a version into a new diagram.

DECKS

Method	Path	Description
GET	`/api/spaces/[spaceId]/decks`	List decks. Same as list_decks.
POST	`/api/spaces/[spaceId]/decks`	Create a deck from an ordered list of diagram ids.
GET	`/api/spaces/[spaceId]/decks/[id]`	Fetch one deck with its ordered slides.
PATCH	`/api/spaces/[spaceId]/decks/[id]`	Update title, description, or slide order.
DELETE	`/api/spaces/[spaceId]/decks/[id]`	Delete a deck.

COMMENTS

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/comments`	List comments. Same as list_comments.
POST	`/api/spaces/[spaceId]/diagrams/[id]/comments`	Post a comment (optionally pinned to a node).
PATCH	`/api/spaces/[spaceId]/diagrams/[id]/comments/[cid]`	Edit a comment body.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]/comments/[cid]`	Delete a comment.
POST	`/api/spaces/[spaceId]/diagrams/[id]/comments/[cid]/resolve`	Resolve or reopen a comment thread.

Method	Path	Description
GET	`/api/spaces/[spaceId]/diagrams/[id]/shares`	List active share links.
POST	`/api/spaces/[spaceId]/diagrams/[id]/shares`	Mint a new share link.
DELETE	`/api/spaces/[spaceId]/diagrams/[id]/shares/[shareId]`	Revoke a share link.
GET	`/api/public/share/[slug]`	Public read endpoint (no auth).

TOKENS

Method	Path	Description
GET	`/api/spaces/[spaceId]/tokens`	List API tokens (no secrets).
POST	`/api/spaces/[spaceId]/tokens`	Create a token. Secret returned ONCE.
DELETE	`/api/spaces/[spaceId]/tokens/[id]`	Revoke a token.

找到你的 Space ID

登录后打开 API 令牌页面 — 你当前空间的 ID 会显示在标题旁，可一键复制。

嵌入图表

生成分享链接,打开 Embed 标签页并复制代码片段 —— 或自行构建。粘贴到任何允许 iframe 的页面。

粘贴到任意页面

<iframe src="https://diagramzu.ai/embed/your-diagram" width="100%" height="480" style="border:0;border-radius:8px" loading="lazy" title="diagramzu diagram"></iframe>

URL 选项

Parameter	Values	Default	Effect
`theme`	`light` `dark` `auto`	`auto`	渲染图表的配色主题。auto 跟随访问者的操作系统。
`bg`	`transparent` `white` `paper` `ink-tint` `dark`	`transparent`	图表背后的背景。transparent 让宿主页面的颜色透出。
`fit`	`true` `false`	`true`	加载时将图表缩放以适应框架。设为 false 则按原始尺寸渲染。
`badge`	`true` `false`	`true`	在角落显示小小的「diagramzu」链接。设为 false 可隐藏。