
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 分