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 分