Excaliwow

@excaliwow/mcp

Excaliwow Model Context Protocol 服务可让 AI Agent 通过与 CLI 相同的公共 REST API（/api/v1），在你的 Excaliwow 账户中创建、读取、渲染、管理和编辑图表。它通过 stdio 运行，因此任何 MCP 客户端（Claude Desktop、Claude Code 等）都可以通过 npx 启动它。

公共 excaliwow/mcp 仓库包含此软件包的分发元数据和文档；托管应用的源代码未在该仓库中发布。

安装

首先，在 https://excaliwow.com/app/settings（Settings → Developer / API tokens）创建一个具有 read + write 权限的 Personal Access Token——这足以使用 18 个工具中的 16 个。只有在希望 Agent 删除和恢复图表时，才添加 delete 权限（参见安全注意事项）。将其作为 EXCALIWOW_TOKEN 传入。

Claude Code（CLI）

只需一条命令。--scope local 会将服务保存在你自己的设置中，因此令牌不会落入可能提交的文件中。先导出令牌，避免将明文 PAT 写入 shell 历史记录——--env NAME="$NAME" 会传递令牌值，无需在命令行中再次输入：

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

Claude Desktop（及其他 JSON 配置客户端）

将其添加到客户端的配置文件中（例如 Claude Desktop 的 claude_desktop_config.json，或客户端的 MCP 设置——请参阅客户端的 MCP 配置文档）。该规范没有版本号，因此 npx -y 始终会启动最新版本——你会自动获得新工具和修复，无需更新版本号：

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

该服务会在每次调用时从环境变量读取 EXCALIWOW_TOKEN（或者，如果你也使用 @excaliwow/cli 并运行过 excaliwow auth login，则读取已保存的登录信息），且不会自行将令牌写入磁盘。

故障排除

“未通过身份验证” / 401 / Agent 的工具调用失败。 即使没有令牌，服务也会启动（以便列出可用工具），因此只有当 Agent 首次调用工具时，缺失或无效的 EXCALIWOW_TOKEN 才会显现。未设置令牌时，启动会向 stderr 输出一行 EXCALIWOW_TOKEN is not set 警告。要直接检查令牌，请运行健康检查——它会执行一次经过身份验证的读取，并输出明确结果（ok、401 — token is invalid or expired，或 API 本身无法访问时的 could not reach <url>），然后以相应代码退出（0 表示正常，1 表示令牌缺失或无效，2 表示无法访问）：

npx -y @excaliwow/mcp --health

CLI 参数

参数	作用
--health	检查令牌和 API 的可访问性，然后退出（0 表示正常，1 表示令牌缺失或无效，2 表示无法访问）。
--version	打印已安装的版本并退出。
--help	打印用法说明（参数和环境变量）并退出。

工具

共 18 个工具，专为安全的 Agent 使用而设：

工具	能力	功能说明
generate_diagram	write	根据高层节点/边 DSL 创建图表（自动布局）；返回编辑器 URL。适合快速绘制流程图。
create_scene	write	根据原始 Excalidraw 场景创建丰富的手工绘制图表——可完全控制布局、样式和排版。
read_diagram	read	提供精简摘要（标题 + 各类型计数）以及渲染后的 PNG；启用 includeGeometry 可获取边界列表。
get_scene	read	返回图表的完整原始场景（{ elements, appState }）以供编辑——读取 → 修改 → regenerate_diagram。
export_diagram	read	将图表渲染为完整保真度的字节以便保存（PNG base64，或作为原始文本的 SVG）——这是要保留的字节，而非视觉图像。
list_diagrams	read	分页查看图表（filter: active | trash）。
move_diagram	write	将图表移至文件夹（或移至根目录）。
edit_diagram	write	以累加方式合并 DSL 片段（添加节点/边，更新节点样式/标签）。
regenerate_diagram	write	原位替换图表内容——使用新的 spec（重新布局）或原始 scene，并保留相同 ID。
trash_diagram	delete	将图表软删除至回收站。可撤销（参见 restore_diagram）。
restore_diagram	delete	恢复已移至回收站的图表，并以其原始 ID 和 URL 重新打开。
lint_diagram	read	检查图表是否存在重叠、标签被裁切、元素超出画框以及文本对比度过低等问题。
patch_elements	write	原位应用可寻址元素的增量变更（添加/更新/移动/调整大小/更改样式/删除）——成本最低的编辑方式。
generate_from_template	write	根据命名布局模板（swimlane、layered-stack、matrix、container-with-children）创建图表。
list_icons	read	列出可通过 image 元素和 icon-<name> fileId 嵌入的精选图标（ID + 标签 + 类别）。
list_folders	read	列出调用者的文件夹（ID + 名称 + parentId），以解析或查找 folderId。
create_folder	write	创建文件夹（可选择嵌套在 parentId 下），用于整理图表。
rename_diagram	write	仅更改图表标题，不影响其内容和 ID/URL。
read_diagram 返回摘要和图像，不会返回原始场景 JSON，以保持上下文精简。传入 includeGeometry: true，还可获取精简且有界的 { id, type, label, x, y, w, h } 列表（x/y 为左上角坐标），让 Agent 能以编程方式检测标签与框之间的碰撞或错位节点，而不必目测 PNG。该列表源自场景，因此即使渲染失败也会提供；它是包含固定字段的小型摘要，并非原始元素转储。
改为传入 includeScene: 'compact'，即可获取有界且可按元素寻址的投影——它包含几何字段的全部内容，还带有样式、文本以及容器/绑定引用（每个元素 ≤17 个字段）——这是 read_diagram → patch_elements 精细编辑流程中的读取环节。
export_diagram 返回要保存到文件的渲染字节——PNG 以 base64 形式返回，SVG 以原始文本形式返回——这与返回图像块供视觉模型查看的 read_diagram 不同。MCP 服务通过 stdio 运行，无法写入你的代码库，因此拥有文件系统访问权限的客户端（例如 Claude Code）会自行解码并保存这些字节。或者，跳过模型中转，直接使用 CLI 将内容写入磁盘：`excaliwow diagrams render -o
docs/architecture.png（或 .svg`）——当渲染结果过大、无法内联返回时，也可使用此方式作为备用方案。

trash_diagram / restore_diagram 是一对可逆操作，受 delete capability 限制——它们始终会注册；除非令牌包含 delete，否则会返回干净的 insufficient_scope 错误（不会更改任何内容），因此只有 read + write 权限的令牌无法删除任何内容。硬删除/清除以及将图表公开分享，有意不作为 Agent 工具提供——这些操作不可逆，因此即使 Agent 受到误导，也无法销毁或暴露你的图表。请通过控制面板或 CLI 执行清除或发布操作。

两种创作方式

generate_diagram 接受高级节点/边 DSL 并自动布局——只想快速绘制流程图时，请使用它。create_scene 接受手工编写的原始 Excalidraw 场景，因此 Agent 可以控制每个元素的位置、大小、颜色、描边、填充、字体排版和连接关系——适用于制作丰富、精致的自定义图表。你只需_简洁_地编写元素（id、类型、几何信息、文本、颜色），其余 Excalidraw 样板内容会自动补齐；完整指定的元素（或粘贴的 .excalidraw 场景）则会原样传递。要迭代优化丰富的图表：get_scene → 编辑元素 → 使用编辑后的 scene 调用 regenerate_diagram。

发现资源

DSL 语法和完整示例内嵌在 generate_diagram 工具说明中；完整参考文档则作为 MCP 资源提供，地址为 excaliwow://dsl/reference。丰富场景创作入门指南和完整示例内嵌在 create_scene 说明中；完整指南（涵盖每种元素类型、所有样式属性、绑定、组、画框、调色板以及布局/美观性启发规则）位于 excaliwow://scene/authoring。

环境变量

变量	作用
EXCALIWOW_TOKEN	必需（独立运行时）。Bearer PAT；每次调用时读取，此服务绝不会将其写入磁盘。
EXCALIWOW_API_URL	API 源站。默认为 https://excaliwow.com；通常无需设置。

要求

Node >= 22.11.0。这是支持政策的最低版本要求，并非技术要求——此处发布的内容没有使用任何仅限 Node 22 的 API（代码中最新的运行时依赖是全局 fetch，从 Node 18 起便已提供）；该最低版本跟随“当前 LTS”，确保 npx -y @excaliwow/mcp 能在我们实际测试过的 Node 版本上运行，并与 @excaliwow/cli 的最低版本要求一致。如果你的 MCP 客户端受限于较旧的 Node，导致 npx 拒绝运行此服务，这是有意为之——请升级 Node，不要将其视为 bug。

安全说明

• 不要将令牌放入任何提交的内容中。 存储在仓库中的项目级配置（已提交的 .mcp.json，或 claude mcp add --scope project）会将令牌写入 git 历史记录。请使用用户级或本地级配置 （--scope local），或改为引用环境变量，而不是粘贴令牌明文。
• 在命令行中输入令牌明文会将其写入 shell 历史记录 （~/.zsh_history、~/.bash_history 等），并短暂出现在进程列表中。 先执行一次 export EXCALIWOW_TOKEN=…，然后通过 --env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" 传递令牌（或从密钥管理器中读取）， 而不是将 PAT 粘贴到 claude mcp add 命令本身中。
• 创建令牌时选择 read + write（只有在需要垃圾回收/恢复时才添加 delete）。 18 个工具中有 16 个只需要 read + write；即使 Agent 受到误导， read + write PAT 也无法公开你的图表或删除图表（trash_diagram / restore_diagram 只会返回 insufficient_scope，不会执行任何操作）。只有在希望 Agent 能够软删除和恢复时， 才添加 delete 能力——此操作可逆，但仍应谨慎授予这项能力。请单独选择所需能力， 不要使用宽泛的 read-write 预设，因为它还会授予 publish（和 delete）。
• 该令牌是你账户的凭据。它只保存在 MCP 客户端配置/环境中；此服务不会持久化令牌。 请像对待任何密钥文件一样保护该配置。

支持

发现 bug 或有疑问？请参阅 excaliwow.com/docs/mcp， 或通过 excaliwow.com/contact 联系我们。

许可证

Apache-2.0 — 请参阅 LICENSE 和 NOTICE。