
Excaliwow
io.github.excaliwow由 GitHub 帳號 excaliwow 發布v0.14.3更新於 Oct 24, 2026
Create, read, render, organize, and safely edit persistent Excalidraw diagrams with AI agents.
概覽
讓 AI 助理在 Excaliwow 帳戶中建立、讀取、算圖、整理與編輯可長期保存的 Excalidraw 圖表。
- 可以做什麼
- 透過節點/邊 DSL、具名版面範本或手寫 Excalidraw 場景建立圖表
- 讀取圖表摘要與算圖 PNG,可選擇附上幾何資訊或精簡場景資料,並匯出 PNG 或 SVG 位元組
- 就地編輯圖表:合併 DSL 片段、以元素為單位套用修補、重新產生內容、修改標題
- 整理圖表:分頁列出使用中或回收筒中的圖表、移至資料夾、建立資料夾、列出可嵌入的圖示
- 檢查版面問題,例如元素重疊、標籤被裁切、超出畫框與低對比文字
- 權杖具備 delete 權限時可將圖表移入回收筒並還原
- 適用情境
- 適合讓助理草擬流程圖或架構圖、在既有圖表上反覆調整,或在 Excaliwow 帳戶中維護圖表庫,也包含在分享前檢查圖表版面。
- 執行需求
- 透過 npx 以 stdio 在本機執行,需要 Node.js 22.11.0 以上版本。需在 EXCALIWOW_TOKEN 提供具備 read 與 write 權限的 Excaliwow 個人存取權杖(若需回收筒與還原再加 delete)。EXCALIWOW_API_URL 為選用,預設使用託管服務;需要能連線至該 API 的網路。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Excaliwow,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
@excaliwow/mcp
The Excaliwow Model Context Protocol server — lets an AI agent create, read,
render, manage, and edit diagrams in your Excaliwow account through the same
public REST API (/api/v1) the CLI uses. It runs over stdio, so any MCP
client (Claude Desktop, Claude Code, etc.) can launch it with npx.
The public excaliwow/mcp repository contains
distribution metadata and documentation for this package; the hosted application
source is not published there.
Install
First mint a Personal Access Token at https://excaliwow.com/app/settings
(Settings → Developer / API tokens) with read + write capabilities —
enough for sixteen of the eighteen tools. Add delete only if you want the agent
to trash and restore diagrams (see Security notes). Pass it as
EXCALIWOW_TOKEN.
Claude Code (CLI)
One command. --scope local stores the server in your own settings, so the
token never lands in a file you might commit. Export the token first so the
literal PAT never lands in your shell history — --env NAME="$NAME" passes
the value through without typing it a second time on the command line:
Claude Desktop (and other JSON-config clients)
Add it to your client's config file (e.g. Claude Desktop's
claude_desktop_config.json, or your client's MCP settings — see your client's
MCP setup docs). The spec is unversioned, so npx -y always launches the latest
release — you pick up new tools and fixes automatically, with nothing to bump:
The server reads EXCALIWOW_TOKEN per call from the environment (or, if you also
use @excaliwow/cli and have run excaliwow auth login, that stored login) and
never writes the token to disk itself.
Troubleshooting
"Not authenticated" / 401 / the agent's tool calls fail. The server starts
even without a token (so it can list its tools), so a missing or invalid
EXCALIWOW_TOKEN only surfaces when the agent first calls a tool. Starting with
no token prints a one-line EXCALIWOW_TOKEN is not set warning to stderr. To
check a token directly, run the health probe — it makes one authenticated read
and prints a clear verdict (ok, 401 — token is invalid or expired, or
could not reach <url> when the API itself is unreachable) and exits with a
matching code (0 ok, 1 missing/invalid token, 2 unreachable):
CLI flags
Tools
Eighteen tools, scoped to safe agent use:
read_diagram returns a summary + image, never the raw scene JSON, to keep
context small. Pass includeGeometry: true to additionally get a compact,
bounded { id, type, label, x, y, w, h } list (top-left x/y) so the agent can
detect label/box collisions or misplaced nodes programmatically instead of
eyeballing the PNG — it is derived from the scene, so it is present even when the
render fails, and it is a small fixed-field summary, not the raw element dump.
Pass includeScene: 'compact' instead for a bounded, element-addressable
projection — a superset of the geometry fields that also carries style, text,
and container/binding refs (≤17 fields/element) — the read half of the
read_diagram → patch_elements surgical-edit loop.
export_diagram returns the rendered bytes to save to a file — png as
base64, svg as raw text — distinct from read_diagram, which returns an image
block for a vision model to look at. An MCP server runs over stdio and cannot
write to your repo, so a client with filesystem access (e.g. Claude Code) decodes
and saves the bytes itself. Or skip the round-trip through the model and stream
straight to disk with the CLI: excaliwow diagrams render <id> -o docs/architecture.png (or .svg) — also the fallback when a render is too large
to return inline.
trash_diagram / restore_diagram are a reversible pair
gated on the delete capability — registered always, they return a clean
insufficient_scope error (changing nothing) unless the token carries delete,
so a read + write token can't trash anything. Hard-delete/purge and making a
diagram publicly shareable are deliberately not agent tools — those are
irreversible, so a misled agent can't destroy or expose your diagram. Purge or
publish from the dashboard or the CLI.
Two authoring paths
generate_diagram takes the high-level node/edge DSL and auto-lays it out —
reach for it when you just want a quick flowchart. create_scene takes a raw,
hand-authored Excalidraw scene, so the agent controls every element's position,
size, color, stroke, fill, typography, and connections — the path for rich,
polished, custom diagrams. You author elements tersely (id, type, geometry,
text, colors) and the Excalidraw boilerplate is filled in for you; a
fully-specified element (or a pasted .excalidraw scene) is passed through
unchanged. To iterate on a rich diagram: get_scene → edit the elements →
regenerate_diagram with the edited scene.
Discovery resources
The DSL grammar + a worked example are embedded in the generate_diagram tool
description, with the full reference served as an MCP resource at
excaliwow://dsl/reference. The rich-scene authoring primer + a worked
example ride in the create_scene description, with the full guide (every
element type, all styling props, bindings, groups, frames, palette, and
layout/beauty heuristics) at excaliwow://scene/authoring.
Environment variables
Requirements
Node >= 22.11.0. This is a support-policy floor, not a technical one —
nothing shipped here uses a Node-22-only API (the code's newest runtime
dependency is global fetch, available since Node 18); the floor tracks
"current LTS" so npx -y @excaliwow/mcp runs on a Node build we actually test
against, and matches @excaliwow/cli's floor. If your MCP client is stuck on
an older Node and npx refuses to run this server, that refusal is
intentional — upgrade Node rather than treat it as a bug.
Security notes
- Keep the token out of anything you commit. A project-scoped config that
lives in the repo (a committed
.mcp.json, orclaude mcp add --scope project) puts the token into git history. Use a user- or local-scoped config (--scope local), or reference an environment variable instead of pasting the literal token. - Typing the literal token on a command line puts it in your shell history
(
~/.zsh_history,~/.bash_history, …) and briefly in the process list.export EXCALIWOW_TOKEN=…once, then pass it through with--env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN"(or pull it from a secrets manager) instead of pasting the PAT into theclaude mcp addcommand itself. - Mint with
read+write(adddeleteonly if you want trash/restore). Sixteen of the eighteen tools need justread+write; aread+writePAT can neither expose your diagrams publicly nor delete them, even if the agent is misled (trash_diagram/restore_diagramsimply returninsufficient_scopeand do nothing). Add thedeletecapability only if you want the agent to be able to soft-delete and restore — it's reversible, but it's still a capability to grant deliberately. Pick capabilities specifically rather than the coarseread-writepreset, which additionally grantspublish(anddelete). - The token is a credential to your account. It lives only in your MCP client config / environment; this server does not persist it. Treat that config the way you'd treat any secrets file.
Support
Found a bug or have a question? See excaliwow.com/docs/mcp or reach us at excaliwow.com/contact.
License
來源:README.md,提交 cbafbf5
工具
0版本歷史
1- v0.14.3最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分