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.

已驗證STDIO僅桌面效率與工作流媒體與設計

概覽

AI 產生的概覽

讓 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 的網路。
安裝前請注意
EXCALIWOW_TOKEN 是帳戶憑證:不要放進會被提交的設定檔或 shell 歷史紀錄,建議使用本機範圍的設定。此權杖可寫入你的圖表,被誤導的助理可能修改或重新整理它們;delete 權限應審慎授予。硬刪除、清除與公開分享並未開放為助理工具。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Excaliwow,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

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:

sh
export EXCALIWOW_TOKEN=excw_pat_…claude mcp add excaliwow --scope local \  --env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" \  -- npx -y @excaliwow/mcp

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:

json
{  "mcpServers": {    "excaliwow": {      "command": "npx",      "args": ["-y", "@excaliwow/mcp"],      "env": {        "EXCALIWOW_TOKEN": "excw_pat_…"      }    }  }}

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):

sh
npx -y @excaliwow/mcp --health

CLI flags

FlagEffect
--healthCheck the token + API reachability, then exit (0 ok, 1 missing/invalid token, 2 unreachable).
--versionPrint the installed version and exit.
--helpPrint usage (flags + env vars) and exit.

Tools

Eighteen tools, scoped to safe agent use:

ToolCapabilityWhat it does
generate_diagramwriteCreate a diagram from the high-level node/edge DSL (auto-laid-out); returns the editor URL. Best for quick flowcharts.
create_scenewriteCreate a rich, hand-authored diagram from a raw Excalidraw scene — full control of layout, style, and typography.
read_diagramreadCompact summary (title + per-type counts) plus a rendered PNG; opt into includeGeometry for a bounds list.
get_scenereadReturn a diagram's full raw scene ({ elements, appState }) for editing — read → mutate → regenerate_diagram.
export_diagramreadRender to full-fidelity bytes to save (png base64, or svg as raw text) — the bytes to keep, not a vision image.
list_diagramsreadPage through your diagrams (filter: active | trash).
move_diagramwriteMove a diagram to a folder (or to root).
edit_diagramwriteAdditively merge a DSL fragment (add nodes/edges, update node style/label).
regenerate_diagramwriteReplace a diagram's contents in place — from a fresh spec (re-layout) or a raw scene, same id.
trash_diagramdeleteSoft-delete a diagram to trash. Reversible (see restore_diagram).
restore_diagramdeleteRestore a trashed diagram, reopening it at its original id and URL.
lint_diagramreadCheck a diagram for overlaps, clipped labels, out-of-frame elements, and low-contrast text.
patch_elementswriteApply element-addressable deltas (add/update/move/resize/restyle/delete) in place — the cheapest edit path.
generate_from_templatewriteCreate a diagram from a named layout template (swimlane, layered-stack, matrix, container-with-children).
list_iconsreadList the curated icons you can embed via an image element + icon-<name> fileId (id + label + category).
list_foldersreadList the caller's folders (id + name + parentId) to resolve or discover a folderId.
create_folderwriteCreate a folder (optionally nested under a parentId) to organize diagrams.
rename_diagramwriteChange only a diagram's title, leaving its contents and id/url untouched.

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

VarEffect
EXCALIWOW_TOKENRequired (standalone). Bearer PAT; read per call, never written to disk by this server.
EXCALIWOW_API_URLAPI origin. Default https://excaliwow.com; normally leave unset.

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, or claude 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 the claude mcp add command itself.
  • Mint with read + write (add delete only if you want trash/restore). Sixteen of the eighteen tools need just read + write; a read + write PAT can neither expose your diagrams publicly nor delete them, even if the agent is misled (trash_diagram / restore_diagram simply return insufficient_scope and do nothing). Add the delete capability 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 coarse read-write preset, which additionally grants publish (and delete).
  • 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

Apache-2.0 — see LICENSE and NOTICE.

來源:README.md,提交 cbafbf5

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.14.3最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分