把你的 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 內的網址中可看到)。

端點清單

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 可隱藏。