把 DiagramZu 加到 Claude Code 或 Cursor

安装 MCP 服务器，生成令牌（或用 Claude 连接器），智能体就能把 Mermaid 写到团队打得开的 URL。快速上手、工具参考与 REST。

第一次用 DiagramZu？先看六个核心概念 →

本页内容

快速开始

三步把你的 AI 接上 DiagramZu。

STEP 01

注册

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

STEP 02

创建 API 令牌

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

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

查找空间中的图表。

使用时机在 create_diagram 之前调用，以免与同名图表重复——用 q 搜索标题、说明或源码。创建后再调用一次，找到最新匹配。

示例

{
  "q": "DB schema",
  "sort": "relevance"
}

list_folders

列出空间中的文件夹。

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

示例

{}

get_diagram

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

使用时机决定改什么之前，先把描述当简报读一遍。

示例

{
  "id": "dgm_abc123"
}

list_versions

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

使用时机做有风险的覆盖之前先调用，看看有哪些恢复点。

示例

{
  "diagramId": "dgm_abc123"
}

get_version

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

使用时机读取过去的快照，了解图表怎么演变，或找回当前版本已经没有的内容。

示例

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

写入工具

create_diagram

在空间中创建图表。

使用时机始终先写描述——它就是留给后续调用的智能体的简报。设置 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 会显示在标题旁，可一键复制。

嵌入图表

生成分享链接，打开「嵌入」标签页复制代码片段——也可以自己拼一个。粘贴到任何允许 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 可隐藏。