mcp-excalidraw

Excalidraw MCP 服务、CLI 和 Agent 技能

mcp-excalidraw-server 为 AI Agent 提供一个实时的 Excalidraw 画布，让它们可以在上面绘图、查看、完善，并将结果保存到你的代码库中。你的 Agent 可以通过编程方式创建架构图和流程图，通过截图查看自己的作品、修复布局问题，并导出 .excalidraw 文件，让你与代码一起提交。

一个画布，三种驱动方式：

• Agent 技能 + CLI — 推荐用于编码 Agent（Claude Code、Codex CLI、Cursor、OpenCode）：npx -y mcp-excalidraw-server <command>。无需配置，自动启动画布，支持组合式 JSON 输入/输出。
• MCP 服务 — 通过 stdio 提供 26 个工具，可供任何 Model Context Protocol 客户端使用（Claude Desktop、Cursor、Codex CLI、Antigravity 等）。支持 MCP 2026-07-28（server/discover、每个请求的 _meta 封装、无需握手即可调用工具），并保持与使用 initialize 启动的 2025 年客户端兼容。
• REST API — 面向 LangChain 和自定义框架的纯 HTTP 接口。

核心绘图功能在本地运行（Node ≥ 20，MIT 许可）——无需 API 密钥或账号。Mermaid 转换在本地浏览器画布中运行；share 为可选功能，会将加密后的场景上传到 excalidraw.com。画布页面会从 esm.sh CDN 加载 Excalidraw 的字体。

演示

AI Agent 根据单条提示词创建完整的架构图（4 倍速）。在 YouTube 上观看完整视频

目录

• 演示
• 简介
• 与官方 Excalidraw MCP 的区别
• 最新内容
• 安装
• Agent 技能
• CLI 参考
• 无头渲染
• 配置 MCP 客户端
  • Claude Desktop
  • Claude Code
  • Cursor
  • Codex CLI
  • OpenCode
  • Antigravity（Google）
• MCP 工具（共 26 个）
• 快速开始（从源代码 / Docker）
• 测试
• 常见问题
• 故障排除
• 已知问题 / 待办事项
• 开发
• 许可证

简介

让你的 Agent “绘制这个服务的架构图”，它就会生成真正可编辑的 Excalidraw 图表——而不是一次性图片。由于 Agent 可以查询、截屏和更新单个元素，因此它会反复调整，直到标签合适、元素不重叠、箭头路径清晰；随后将结果导出为 .excalidraw 文件，保存在你的代码库中，并在代码发生变化时更新。

底层由两个进程构成，却只提供一个产品：

• 画布服务：Excalidraw 网页界面 + REST API + WebSocket 实时同步（默认地址为 http://127.0.0.1:3000）
• 你选择的轻量前端：CLI、MCP stdio 服务或原始 HTTP——它们都驱动同一个画布

从 v1.1 开始，画布服务会自行启动：如果当前没有服务在监听，驱动画布的 CLI 命令（以及启动时的 MCP 服务）会自动启动它。status 只检查当前服务状态。设置 EXCALIDRAW_NO_AUTOSTART=1 可选择禁用此功能。

我们与官方 Excalidraw MCP 的区别

Excalidraw 有一个官方 MCP——一个聊天小组件，可根据单条提示词以内嵌方式流式生成图表（模型会获得两个工具：格式参考和 create_view）。它非常适合在 Claude 或 ChatGPT 中说“给我画只猫”。我们要解决的是另一个问题：为编码 Agent提供持久的画布工作台。

	官方 Excalidraw MCP	本项目
方式	输入提示词，输出图表（一次性小组件）	以编程方式控制各个元素（CLI + 26 个 MCP 工具）
状态	聊天小组件内的检查点	实时画布，支持实时同步和可选的重启安全检查点
元素增删改查	以声明方式重新发送，并使用删除标记	可对每个元素进行完整的创建／读取／更新／删除操作
AI 能看到画布	否	describe（结构化文本）+ screenshot（图像）
迭代优化	从检查点重新生成	绘制 → 查看 → 调整 → 再查看，逐个元素迭代
布局工具	无	对齐、分布、编组／取消编组、锁定、复制
文件输入／输出	不支持面向模型的导出	.excalidraw 导入／导出——将图表作为仓库产物
快照与回滚	小组件端的检查点	服务端命名快照
Mermaid 转换	无	mermaid / create_from_mermaid
可分享 URL	仅支持小组件	share / export_to_excalidraw_url
视口控制	摄像机动画	set_viewport（缩放至适合所有或所选元素、将某个元素居中、手动缩放）
无需 MCP 也能工作	否	是——CLI + Agent 技能 + REST API
多 Agent	单个聊天	多个 Agent 可同时操作同一画布

简而言之——官方 MCP 会在聊天中展示 Excalidraw 图表。本项目则为你的编码 Agent 提供完整的 Excalidraw 工作台：它可以在画布上绘制、检查、优化，并将成果提交到你的仓库。

更新内容

当前软件包版本：2.1.2。当前发布系列为 v2.1 — 无头渲染。

v2.1.2 — 修复

• 恢复快照不再清空画布；现在可以恢复和导入画框。（#101，感谢 @sanjayy0612；#120）
• 即使经过更新和重命名，每个形状也只会有一个标签。（#121，感谢 @sdrshn-nmbr）
• 添加的图像在重新加载后仍会保留，并显示在导出内容中。（#122，感谢 @appdesigngeeks）
• 字体较晚加载时，文本不再被裁切。（#123，#124）

v2.1.1 — 修复

• 大型导出不再因 invalid order key 而失败。（#115，感谢 @fernandovmacedo）
• 每次画布同步时，文本和箭头不再偏移。（#116，感谢 @hidinginabunker）
• 库可以正常安装并持久保存；调整大小时标签会重新换行。（#113，感谢 @lukemariano）

v2.1 — 无头渲染

• 截图和图像导出不再需要浏览器标签页。 screenshot、export_to_image 和 get_canvas_screenshot 会在画布服务中渲染：Excalidraw 自带的 SVG 导出器在 Node（jsdom）下运行，resvg 使用随附的 Excalifont/Virgil/Cascadia/Liberation 字体将其栅格化为 PNG。输出与标签页中的结果一致且具有确定性（场景未变化时，字节完全相同），每次渲染只需几毫秒，并且可在 CI 和 Docker 中运行。请参阅无头渲染。
• CLI、REST 和 MCP 新增渲染选项：dark、scale（1–4）、padding、elementIds（渲染部分元素）、frameId（渲染一个画框）、embedFonts。--renderer browser 可继续使用旧的标签页渲染方式。
• 新增 render 命令：npx -y mcp-excalidraw-server render docs/arch.excalidraw --out docs/arch.png 可离线渲染已提交的文件——完全无需画布服务。
• 创建时未指定 width／height 的形状，现在在导出和渲染时默认使用 100×100（与画布一致），而不再缩为 0×0。
• 导出时会重新测量存储为 width: 0, height: 0 的文本（来自 2.0 之前服务器的场景），而不是导出不可见的内容。（#107）

v2.0 — 互操作级导出与 MCP 2026-07-28

• 破坏性变更：要求 Node >= 20（之前为 18）——MCP TypeScript SDK v2 提高了最低版本要求。其他所有内容均向后兼容，包括现有的 MCP 客户端配置。
• MCP 协议修订版 2026-07-28：现代客户端无需初始化握手即可无状态地调用工具（server/discover、每个请求的 _meta 信封）；基于传统初始化流程的客户端仍可照常使用。（#98，感谢 @anxkhn）
• 导出现在可在任何地方正常呈现：.excalidraw / .excalidraw.md 文件包含真正的 Excalidraw 元素——形状和箭头标签作为绑定文本，箭头绑定保持有效——因此在 excalidraw.com 和 Obsidian Excalidraw 插件中都能正确打开，不再丢失标签（也不会被插件重新保存为空文件）。（#93、#95）
• 字节稳定的导出：ID、种子和键顺序均为确定性值——未更改的场景重新导出后字节完全一致，因此已提交的图表和知识库文件不会产生虚假的 git 差异，Obsidian 块引用也能在重新导出后保留。
• Obsidian 知识库修复：Windows/CRLF .excalidraw.md 文件现在可以正确导入（#94，感谢 @cason-miles）；## Text Elements 块引用现在也涵盖形状标签。
• 元素字段不会再被静默丢弃：未知的 Excalidraw 属性（containerId、textAlign、originalText 等）会完整地通过服务端传递——修复了浏览器编辑的文本在同步后消失的问题。（#92，感谢 @junuxyz）
• Mermaid 转换现在会合并到现有画布，而不是替换画布；每个浏览器标签页也只会保持一个 WebSocket 连接（不再出现标签重复）。（#91）
• 视口控制：set_viewport 新增 scrollToElementIds（多元素缩放至适配）和 viewportZoomFactor，并提供严格的单模式验证和真实错误报告。（#86，感谢 @acercyc）
• 深色模式：画布页面外观会跟随编辑器主题，并在重新加载后保留该主题。（#89，感谢 @danielsvane）

v1.1 — CLI 优先

• 一流的 CLI：现在每项功能都可组合为命令——npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|...——JSON 输出到 stdout，并返回有意义的退出码。也可通过 excalidraw-canvas 别名安装。
• 零配置：驱动画布的 CLI 命令和 MCP 服务会在画布服务未运行时自动启动（解决 #66）。使用 EXCALIDRAW_NO_AUTOSTART=1 可禁用此功能。
• apply：在单次调用中执行多项操作补丁（{"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}）。
• install-skill：npx -y mcp-excalidraw-server install-skill --dir <skills-root> 会将可移植的 Agent 技能复制到 Agent 选择的目录（项目级或全局），并干净地替换旧版本。
• 技能现在以 CLI 为先，无需克隆仓库或配置 MCP 服务即可使用。
• 类型化查询：query --filter locked=true --filter label.text=API——支持布尔值、数字和嵌套键。
• 内部实现：CLI 和 MCP 服务现共用核心库（src/core/）；画布的 groupIds 是分组的事实来源（取消分组现在可跨重启生效）；移除了 node-fetch；MCP 版本元数据从 package.json 派生；画布服务会写入 pidfile 并正常关闭。

安装

唯一的前置条件是 Node.js ≥ 20。

最简单的方法：让你的 Agent 安装

将以下内容复制到你的编码 Agent 中——它会把可移植技能安装到该 Agent 已知如何使用的项目级或全局技能目录中，然后通过绘制测试图表进行验证：

Install the Excalidraw canvas toolkit so you can draw diagrams for me:

1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
   then tell me I can open http://127.0.0.1:3000 to watch you draw (optional).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
   screenshot, and show me the result to confirm everything works.

手动安装

您是……	使用以下命令安装	然后
现代编码 Agent	npx -y mcp-excalidraw-server install-skill --dir <skills-root>	让 Agent 选择项目级或全局范围，以及其技能根目录
Claude Code 快捷方式	npx -y mcp-excalidraw-server install-skill	安装到 ~/.claude/skills，以保持向后兼容
Codex 快捷方式	npx -y mcp-excalidraw-server install-skill --target codex	安装到 ~/.codex/skills，以保持向后兼容
MCP 客户端用户（Claude Desktop、Cursor 等）	添加下面的 npx 配置	请参阅配置 MCP 客户端
CLI 用户／脚本编写者	无需安装 — npx -y mcp-excalidraw-server <command>	请参阅CLI 参考
贡献者／从源代码安装	git clone + npm ci + npm run build	请参阅快速开始（从源代码／Docker）

无需单独设置服务：任何绘图命令都会自动启动本地画布服务 http://127.0.0.1:3000。

60 秒快速开始（CLI）

无需克隆，无需配置：

# start the canvas (drawing commands auto-start it too) and open it
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # optional: watch live (only mermaid needs the tab)

# draw something
echo '[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# let your agent see its work
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# diagrams as repo artifacts
mkdir -p docs
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

# or straight into an Obsidian vault (.md extension → Obsidian Excalidraw plugin format)
npx -y mcp-excalidraw-server export --out ~/vault/diagrams/architecture.excalidraw.md

向 Agent 提供完整的操作指南：

npx -y mcp-excalidraw-server install-skill --dir <skills-root>
npx -y mcp-excalidraw-server install-skill --print-source  # inspect bundled source path

安全提示： 画布服务默认仅绑定到 127.0.0.1。如果要在网络接口上公开服务（HOST=0.0.0.0），请在前面设置网络级访问控制 — API 没有内置身份验证。

Agent 技能

skills/excalidraw-skill/ 中的技能会教会 Agent 完整工作流 — 布局规划、截图验证修复质量循环、箭头路由、反模式、快照和文件 I/O。它可通过 CLI（首选，无需设置）、MCP 工具（如已配置）或原始 REST 使用，优先级依次递减。

npx -y mcp-excalidraw-server install-skill --dir <skills-root>

该命令会将捆绑的 excalidraw-skill/ 目录复制到 <skills-root>/excalidraw-skill。让 Agent 选择该根目录应设为项目级还是全局级。重新运行 install-skill 会就地升级 — 它会替换目标目录，因此上游已删除的文件不会残留。

该技能的优势：

• 将图表作为代码工件：将 .excalidraw 文件导出到代码库中并提交；架构发生变化时，再重新导入并完善。
• Obsidian 知识库：使用 .excalidraw.md 扩展名导出，文件即可在 Obsidian Excalidraw 插件 中原生打开 — 不会出现兼容模式警告，块引用和同步也能正常工作；import 还可以读回普通格式和 lz-string 压缩的知识库文件。
• 自我验证的图表：Agent 会为自己的作品截图，并在完成前修复内容截断或重叠问题。
• 无需 MCP 的环境：CI 作业、普通 Shell 和框架也能通过 CLI 获得相同能力。

CLI 参考

npx -y mcp-excalidraw-server <command>，或（执行 npm i -g mcp-excalidraw-server 后）excalidraw-canvas <command>。

约定：JSON 结果输出到 stdout——但 describe 除外（设计为纯文本），以及省略 --out 时的原始内容输出（export 输出场景 JSON，screenshot --format svg 输出 SVG）。诊断信息输出到 stderr。退出码：0 成功，1 错误，2 用法错误，3 画布无法访问，4 需要浏览器标签页（仅适用于 mermaid 和 screenshot --renderer browser）。画布 URL 来自 EXPRESS_SERVER_URL 或 --url。驱动画布的命令会自动启动服务；status 仅报告当前状态。显式执行 start 会覆盖 EXCALIDRAW_NO_AUTOSTART=1 的退出选项（这是用户的明确意图，并非自动启动）。

命令	描述
start / stop / status	管理画布服务（以分离模式运行；stop 会在发送信号前，通过 /health 验证运行中的服务身份）
add [file|-]	从 JSON 数组批量创建元素（文件或 stdin）；使用 --one '{...}' 创建单个元素
apply [file|-]	一次调用执行多个操作的补丁：{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}
get <id> / delete <id...>	读取 / 移除元素
update <id> --set '{...}'	更新元素
query	--type、--bbox x0,y0,x1,y1、--filter k=v（支持类型化的嵌套键）、--filter-json '{...}'
describe	AI 可读的场景摘要（纯文本）
screenshot	无头渲染画布（无需浏览器标签页）：--out f.png|f.svg、--format png|svg、--scale 1-4、--dark、--padding N、--no-background、--ids a,b、--frame <id>、--no-embed-fonts、--embed-scene（可编辑 PNG）；--renderer browser 则使用已打开的标签页
render [file|-]	离线将 .excalidraw / .excalidraw.md / 含嵌入场景的 PNG 文件渲染为 PNG/SVG——无需画布服务，使用与 screenshot 相同的标志
export [--out f.excalidraw] [--format json|obsidian] / import [file|-] [--replace]	场景文件 I/O——.md 输出路径会写入 Obsidian 的 .excalidraw.md 格式；import 也会读取含嵌入场景的 PNG
mermaid [file|-]	Mermaid → 画布（需要浏览器标签页）
snapshot save|list|restore <name>	命名快照
arrange align|distribute|group|ungroup|lock|unlock|duplicate	布局操作（--ids a,b,c、--to left|horizontal|...）
share	加密上传 → 可分享的 excalidraw.com URL
clear --yes	清空画布
install-skill [--dir <skills-root>]	安装可移植的 Agent 技能

在 CLI 中，标签和箭头绑定处处使用便于 Agent 操作的格式：任意形状上的 "text"，以及箭头上的 "startElementId" / "endElementId"——会自动规范化。对于原生框架，添加一个带有 "name" 的 "type":"frame" 元素，并在其子元素上设置 "frameId"。

无头渲染

从 v2.1 起，screenshot、export_to_image 和 get_canvas_screenshot 无需浏览器即可渲染。在画布服务内部，场景会使用画布标签页自身的代码进行准备（标签尺寸、换行和居中、默认值），然后由 Excalidraw 自带的 exportToSvg 在 Node 下绘制（小型 jsdom 垫片提供其所需的 DOM，文本则使用捆绑字体的实际字形宽度进行测量）；resvg 会将 SVG 光栅化为 PNG。输出内容与 Excalidraw 画布绘制的内容一致——SVG 结构与浏览器导出相同，文本误差小于半个像素——且具有确定性：未更改的场景会渲染为字节完全相同的 SVG 和 PNG，因此提交的图像保持干净、无差异。

• 字体：Excalifont、Virgil、Cascadia Code 和 Liberation Sans 以 TTF 格式附带在 assets/fonts 中（均采用 SIL OFL 1.1；参见 assets/fonts/LICENSES.md）。SVG 会嵌入所用字型，因此在浏览器、GitHub 和编辑器中都能正确显示。目前，Nunito、Lilita One 和 Comic Shanns 会使用最接近的捆绑字体进行渲染。其他文字系统（CJK、表情符号）会回退到机器上的字体，并显示警告。
• 选项（CLI 标志 / REST 请求体 / MCP 参数）：background、dark、scale 1–4（PNG）、padding、用于渲染子集的 elementIds 或 frameId、embedFonts、embedScene（仅 PNG，默认 false）。EXCALIDRAW_RENDER_MAX_DIM（默认 8192）会限制 PNG 的最长边。
• --renderer browser 会改为请求打开的画布标签页进行渲染（v2.1 之前的方式）。可用于交叉验证；速度较慢，且会先丢弃标签页中尚未同步的编辑。
• 离线：render docs/arch.excalidraw --out docs/arch.png 完全不需要画布服务——非常适合将图像与已提交的图表一起保存的 CI 作业。
• 仍依赖浏览器：Mermaid 转换（mermaid、create_from_mermaid）和 set_viewport。

渲染器包通过 npm run build:server（dist/render/excalidraw-node.mjs）构建；npm run test:render 无需浏览器即可对其进行测试。

配置 MCP 客户端

MCP 服务通过 stdio 运行。从 v1.1 起，最简单的配置方式是使用 npx——无需克隆、无需绝对路径，且画布会自动启动：

环境变量

变量	描述	默认值
EXPRESS_SERVER_URL	画布服务的 URL	http://127.0.0.1:3000
ENABLE_CANVAS_SYNC	启用画布实时同步	true
EXCALIDRAW_NO_AUTOSTART	设为 1 可禁用画布自动启动	（未设置）
EXCALIDRAW_EXPORT_DIR	MCP 文件导出可写入的基础目录	当前工作目录
EXCALIDRAW_RENDER_MAX_DIM	无头 PNG 的最长边，单位为像素	8192
EXCALIDRAW_DATA_DIR	可选的本地持久状态目录	（未设置；使用内存）
EXCALIDRAW_SHARE_UPLOAD_URL	share 上传加密场景的位置（excalidraw-json POST 端点）	https://json.excalidraw.com/api/v2/post/
EXCALIDRAW_SHARE_BASE_URL	分享链接打开的 Excalidraw 应用	https://excalidraw.com
PORT / HOST	画布服务的绑定地址	3000 / 127.0.0.1
LOG_LEVEL	日志详细程度（error、warn、info、debug）	info
LOG_FILE_PATH	日志文件位置	~/Library/Logs/excalidraw-mcp.log（macOS），$XDG_STATE_HOME/excalidraw-mcp/excalidraw.log（Linux），%LOCALAPPDATA%\Excalidraw-MCP\excalidraw.log（Windows）

持久化画布状态

设置 EXCALIDRAW_DATA_DIR，以便在画布服务重启后恢复元素、服务端已知的图像文件和命名快照。从源码检出目录运行 npm run build 后：

EXCALIDRAW_DATA_DIR=/absolute/private/canvas-data \
  node dist/bin.js start

未设置该变量时，行为和 API 语义仍以内存为准，并且不会创建持久化状态目录。启用后，该目录包含一个带版本的 canvas-state-v1.json 检查点、一个 blobs/ 目录，以及一个运行时 canvas-state.lock/ 所有权目录。图像载荷以不可变的文件 ID blob 形式存储在路径安全的 SHA-256 文件 ID 路径下；检查点记录独立的内容 SHA-256，且仅包含引用。在任何检查点可以引用新 blob 之前，都会先将其刷写并以原子方式发布。每次接受的变更都会先刷写临时检查点并以原子方式重命名，然后服务端才广播或确认该变更。序列化会递归排序对象键，保留场景堆叠顺序，并按稳定的 ID/名称顺序存储文件和命名快照元数据。无效 JSON、不受支持的架构、非普通文件的检查点路径、缺失的 blob 以及 blob 完整性校验失败都会导致启动停止，而不会用空场景替换可恢复状态。

持久化模式下有两条更严格的 REST 规则，违反时都会返回 409：先上传图像文件（POST /api/files），再上传引用它的元素；绝不能使用不同内容重新上传已有文件 ID。画布标签页和 import 已遵循此方式。

如果检查点已重命名到位，但最终目录刷写失败，请求会失败且不会广播成功消息，并且在重启前会拒绝进一步的变更。已发布的场景会保留在内存中，以确保与磁盘上的文件一致；失败的请求可能会出现在恢复的场景中。在 Windows 上，Node.js 不提供目录 fsync，因此存储会刷写文件内容并使用原子发布，但不保证具备同等的目录持久性保障。

数据目录锁可授予一个进程对该持久化状态的独占所有权，即使服务使用不同端口也是如此。它会存储一个与令牌对应的所有者文件，确保回收过期锁时不会删除新所有者的凭据。现有 pidfile 用途不同：用于识别正在监听的进程，以供 start / stop 生命周期命令使用。支持本地文件系统和单个写入者；网络文件系统、共享多写入者访问、自动 blob 垃圾回收、数据库和云端持久化均不在支持范围内。

隐私： 持久化状态包含图表和嵌入的图像载荷。请将该目录放在仓库和共享文件夹之外，限制其权限，并在使用容器时将其挂载为私有可写卷。

---

Claude Desktop

配置位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

npx（推荐）

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

本地（node）

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

---

Claude Code

npx（推荐）

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

提示：对于编码 Agent，技能 + CLI 往往比 MCP 配置更好——让 Agent 选择其技能根目录，然后运行 npx -y mcp-excalidraw-server install-skill --dir <skills-root>。

本地（node） - 用户级（适用于所有项目）：

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

管理服务：

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

---

Cursor

配置位置：项目根目录中的 .cursor/mcp.json（全局配置则为 ~/.cursor/mcp.json）

npx（推荐）

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

---

Codex CLI

npx（推荐）

codex mcp add excalidraw -- npx -y mcp-excalidraw-server

Docker

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

管理服务：

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

---

OpenCode

配置位置：~/.config/opencode/opencode.json 或项目级 opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["npx", "-y", "mcp-excalidraw-server"],
      "enabled": true
    }
  }
}

---

Antigravity（Google）

配置位置：~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

---

备注

• Docker 网络：使用 host.docker.internal 连接运行在主机上的画布服务。在 Linux 上，你可能需要使用 --add-host=host.docker.internal:host-gateway，或使用 172.17.0.1。Docker MCP 镜像会设置 EXCALIDRAW_NO_AUTOSTART=1（该镜像不包含前端构建产物）——请将画布作为独立容器运行。
• 画布持久化：默认情况下，元素和命名快照保存在内存中，服务器重启后会丢失。设置 EXCALIDRAW_DATA_DIR，即可在重启后恢复元素、服务器已知的图像文件和命名快照（参见持久化画布状态）。使用 export 保存独立的 .excalidraw 文件；在默认的内存模式下，仅创建快照无法在重启后恢复数据。

MCP 工具（共 26 个）

类别	工具
元素 CRUD	create_element、get_element、update_element、delete_element、query_elements、batch_create_elements、duplicate_elements
布局	align_elements、distribute_elements、group_elements、ungroup_elements、lock_elements、unlock_elements
场景感知	describe_scene、get_canvas_screenshot
文件 I/O	export_scene、import_scene、export_to_image、export_to_excalidraw_url、create_from_mermaid
状态管理	clear_canvas、snapshot_scene、restore_snapshot
视口	set_viewport
设计指南	read_diagram_guide
资源	get_resource

可通过 tools/list 或 skills/excalidraw-skill/references/cheatsheet.md 查看完整的架构定义。

视口组焦点可通过 viewportZoomFactor 调整取景：

{
  "scrollToElementIds": ["id1", "id2", "id3"],
  "viewportZoomFactor": 0.85
}

scrollToElementIds 会缩放以适配所有指定元素，而 scrollToElementId 会将单个元素居中，且不改变当前缩放级别。每个请求只能指定一种视口模式。viewportZoomFactor 接受大于 0 且不超过 1 的值。

快速开始（从源码运行 / Docker）

从源码运行（Node >= 20）：

npm ci
npm run build
PORT=3000 npm run canvas          # canvas server (terminal 1)
node dist/index.js                # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status           # or drive the CLI straight from the build

Docker 画布服务：

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

MCP 服务镜像：ghcr.io/yctimlin/mcp_excalidraw:latest（stdio；将 EXPRESS_SERVER_URL 指向画布容器）。

测试

CLI 冒烟测试

npx -y mcp-excalidraw-server start
npx -y mcp-excalidraw-server status
npx -y mcp-excalidraw-server add --one '{"type":"rectangle","x":100,"y":100,"width":300,"height":200}'
npx -y mcp-excalidraw-server describe

画布冒烟测试（HTTP）

curl http://127.0.0.1:3000/health

回归检查

npm test 会构建服务并运行四个测试套件，也可以单独运行每个套件：

npm test
npm run test:mcp      # MCP stdio wire protocol (see below)
npm run test:bind     # default loopback bind, duplicate-start refusal
npm run test:render   # headless renderer, export order keys, scene-prep stability
npm run test:state    # atomic import and snapshot restore, sync validation

画布浏览器回归测试

这些 Chromium 测试会构建应用并启动一个隔离的本地主机服务器。测试覆盖画布重新加载和重连、混合场景、加载失败时的同步保护、过期响应、清除和删除、Mermaid 导入、SVG 导出、拖入图像，以及字体加载后的文本测量。如果已有服务器正在运行，测试将拒绝复用；如果端口 51910 已被占用，请设置 CANVAS_TEST_PORT。

npx playwright install chromium
npm run type-check:frontend
npm run test:canvas

MCP Stdio 协议测试

使用原始 JSON-RPC 帧驱动 dist/index.js，并检查两代协议：server/discover、无需任何握手即发送的工具调用、对不受支持的协议修订版本和格式错误的 _meta 封装的拒绝，以及旧版 initialize 路径。

npm run test:mcp

MCP 冒烟测试（MCP Inspector）

列出工具：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

创建矩形：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200

前端截图（agent-browser）

如果你使用 agent-browser 检查 UI：

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

常见问题

这与官方 Excalidraw MCP 有何不同？

官方 Excalidraw MCP 是一个聊天小组件：你输入提示词，它便将图表流式传输到对话中（模型会获得两个工具）。本项目则是一个面向编码 Agent 的工作台：提供持久化的本地画布，支持元素级创建、读取、更新和删除，提供布局工具、模型可查看的截图、快照，以及 .excalidraw 文件 I/O——可通过 CLI、MCP 或 REST 驱动。请参见完整对比表。

它能与哪些 AI 工具配合使用？

下文介绍了 Claude Code、Claude Desktop、Cursor、Codex CLI、OpenCode 和 Google Antigravity——但任何能够运行 shell 命令的 Agent 都可以使用 CLI，任何 MCP 客户端都可以使用 MCP 服务，其他工具（LangChain、自定义应用）则可以使用 REST API。

AI 能看到自己绘制的图表吗？

可以——这是核心功能。describe 会返回结构化的文本摘要（ID、位置、标签、连接关系），而 screenshot 会返回渲染后的 PNG。Agent 会结合两者检查标签是否被截断、是否存在重叠以及箭头路径是否不佳，然后逐个修正元素。

我需要打开浏览器吗？

不需要。截图和 PNG/SVG 导出会在画布服务中以无头方式渲染（参见无头渲染），其他所有操作——创建、查询、更新元素以及处理 .excalidraw 文件——从未需要浏览器。只有两项操作仍需要打开的标签页：Mermaid 转换（会在浏览器中进行布局）和视口控制（会移动摄像机）。遇到这种情况时，CLI 会以代码 4 退出并告知你。打开 URL 仍然是让人类观看 Agent 绘图的方式。

我的图表会持久保存吗？

默认情况下，画布数据存储在内存中（重启后画布为空）。设置 EXCALIDRAW_DATA_DIR，即可在重启后自动恢复元素、服务已知的图像文件和命名快照。需要便于移植和审查的内容仍应导出为 .excalidraw 文件，并在适当时提交到你的仓库中。

excalidraw.com 分享链接是私密的吗？

share 会在上传前在本地使用 AES-GCM 加密场景数据；解密密钥只存在于 URL 片段中，excalidraw.com 的服务器无法看到它。任何拿到完整链接的人都可以查看图表。

分享链接可以指向自托管的 Excalidraw 吗？

可以。将 EXCALIDRAW_SHARE_UPLOAD_URL 设置为你的存储后端的场景端点，并将 EXCALIDRAW_SHARE_BASE_URL 设置为你的 Excalidraw 应用。任何支持 excalidraw-json API 的后端都可使用，例如 alswl/excalidraw-storage-backend，其端点为 <storage>/api/v2/scenes/：

EXCALIDRAW_SHARE_UPLOAD_URL=https://draw.example.com/api/v2/scenes/ \
EXCALIDRAW_SHARE_BASE_URL=https://draw.example.com \
  npx -y mcp-excalidraw-server share

你的应用必须能够从同一后端加载 #json= 链接（对于 alswl 分支：VITE_APP_BACKEND_V2_GET_URL）。

它需要 API 密钥或云服务吗？

不需要 API 密钥。核心绘图功能依据 MIT 许可证在本地运行。出站流量仅包括画布页面从 esm.sh CDN 加载 Excalidraw 字体，以及可选的 share 上传到 excalidraw.com（或你自己的实例，见上文）。CLI、MCP 服务和无头渲染器不会发起其他网络请求。

不配置 MCP 也能使用吗？

可以——这是编码 Agent 推荐的使用方式：运行 npx -y mcp-excalidraw-server install-skill --dir <skills-root>，然后由 Agent 通过 CLI 完成所有操作。只有 Claude Desktop 这类聊天客户端才需要配置 MCP。

故障排查

• CLI 退出代码 3（画布无法访问）：对于 status 等检查命令，服务未运行；自动启动已禁用（EXCALIDRAW_NO_AUTOSTART=1）；或者 EXPRESS_SERVER_URL 指向了非环回主机。请显式运行 start，或修正环境变量。
• CLI 退出代码 4（需要浏览器）：只有 mermaid 和 screenshot --renderer browser 需要打开的标签页——在浏览器中打开 http://127.0.0.1:3000 并重试，或者移除 --renderer browser，改用无头模式渲染。
• 无头 PNG 中的 CJK/emoji 文本显示为方框：捆绑字体支持拉丁文字；对于其他文字，resvg 会回退到机器上的字体（并打印警告）。请在运行画布服务的机器上安装 CJK 字体。
• 画布未更新：确认 EXPRESS_SERVER_URL 指向正在运行的画布服务（status 会显示正在使用的 URL）。
• 画布页面在离线时显示普通字体：页面会从 esm.sh CDN 加载 Excalidraw 的手绘字体，因此无法联网时会回退到系统字体。无头截图和 render 使用捆绑字体，不受影响。
• 其他异常：详情请查看服务日志；日志位置见环境变量（LOG_FILE_PATH）。

已知问题 / 待办事项

• 可选的持久化存储：设置 EXCALIDRAW_DATA_DIR，即可实现本地原子化重启恢复；默认仍使用内存存储。
• Mermaid 转换需要浏览器：mermaid / create_from_mermaid 会在前端布局图表。自 v2.1 起，图像导出和截图均采用无头模式。
• 画布页面字体来自 CDN：由画布服务提供字体，即可让页面完全支持离线使用。

欢迎贡献！

开发

npm run type-check
npm run build
npm run cli -- status      # run the CLI from the local build
npm run sync:skills        # after editing skills/excalidraw-skill, sync the repo-local agent copy

欢迎在 GitHub issues 上提交错误报告和拉取请求。如果这个项目对你有帮助，点个 ⭐ 能让更多人发现它。

许可证

MIT © yctimlin — 与 Excalidraw 团队无关联。Excalidraw 是一个独立的 MIT 许可项目；本工具包基于它构建，倾注了心血。

链接： npm 包 · GitHub · 问题反馈 · 演示视频

如果你想了解后续进展，欢迎在 X 上关注我：@ycalintim。