excalidraw-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excalidraw MCP

Overview

概述

Create and refine diagrams on a live Excalidraw canvas via MCP tools, with helper scripts for export/import workflows.

通过MCP工具在实时Excalidraw画布上创建和优化图表，同时提供用于导出/导入工作流的辅助脚本。

Quick Start

快速开始

Ensure the canvas server is reachable at
```
EXPRESS_SERVER_URL
```
(default
```
http://localhost:3000
```
).
Use MCP tools for interactive diagram edits; use
```
scripts/*.cjs
```
for file-ish workflows (export/import/clear/health).
For detailed endpoint/tool reference, read
```
references/cheatsheet.md
```
.

确保画布服务器可通过
```
EXPRESS_SERVER_URL
```
访问（默认地址为
```
http://localhost:3000
```
）。
使用MCP工具进行交互式图表编辑；使用
```
scripts/*.cjs
```
脚本处理类文件工作流（导出/导入/清空/健康检查）。
如需详细的端点/工具参考，请阅读
```
references/cheatsheet.md
```
。

Workflow: Draw A Diagram (From Empty Canvas)

工作流：从零画布绘制图表

Confirm canvas is up:
- Run
```
node scripts/healthcheck.cjs
```
  (or GET
```
/health
```
  ).
Optional: clear the canvas:
- Run
```
node scripts/clear-canvas.cjs
```
  .
Create shapes first (rectangles/diamonds/ellipses), using
```
create_element
```
.
Put text on shapes by setting the shape’s
```
text
```
field (do not create a separate text element unless you need standalone text).
Create arrows/lines after both endpoints exist.
Use
```
align_elements
```
/
```
distribute_elements
```
after rough placement; group only after layout stabilizes.

确认画布正常运行：
- 运行
```
node scripts/healthcheck.cjs
```
  （或发送GET请求至
```
/health
```
  ）。
可选操作：清空画布：
- 运行
```
node scripts/clear-canvas.cjs
```
  。
首先创建形状（矩形/菱形/椭圆），使用
```
create_element
```
工具。
通过设置形状的
```
text
```
字段为形状添加文本（除非需要独立文本，否则无需创建单独的文本元素）。
在两个端点都创建完成后，再创建箭头/线条。
大致布局完成后，使用
```
align_elements
```
/
```
distribute_elements
```
工具；仅在布局稳定后再进行分组操作。

Workflow: Refine An Existing Diagram

工作流：优化现有图表

Discover what’s already there:

Prefer

get_resource

with

resource: "elements"

query_elements

Identify targets by stable signals (id, type, label text), not by exact x/y.
Update with
```
update_element
```
(move/resize/colors/text) or delete with
```
delete_element
```
.
If deletes/updates “don’t work”, check:
- You’re pointing to the right
```
EXPRESS_SERVER_URL
```
  .
- The element id exists on the canvas (use
```
get_resource
```
  /
```
GET /api/elements/:id
```
  ).
- The element isn’t locked (use
```
unlock_elements
```
  first).

查看画布现有内容：
- 优先使用
```
get_resource
```
  并指定
```
resource: "elements"
```
  ，或使用
```
query_elements
```
  工具。
通过稳定标识（id、类型、标签文本）定位目标元素，而非依赖精确的x/y坐标。
使用
```
update_element
```
工具进行更新（移动/调整大小/修改颜色/文本），或使用
```
delete_element
```
工具删除元素。
如果删除/更新操作未生效，请检查：
- 你指向的
```
EXPRESS_SERVER_URL
```
  是否正确。
- 元素id是否存在于画布上（使用
```
get_resource
```
  / 发送GET请求至
```
/api/elements/:id
```
  ）。
- 元素是否被锁定（先使用
```
unlock_elements
```
  工具解锁）。

Workflow: Export / Import (Repository-Friendly)

工作流：导出/导入（适配仓库场景）

Export current elements to a JSON file:

node scripts/export-elements.cjs --out diagram.elements.json

Import elements (append) using batch create:

node scripts/import-elements.cjs --in diagram.elements.json --mode batch

Import elements (overwrite canvas) using sync:

node scripts/import-elements.cjs --in diagram.elements.json --mode sync

Notes:

```
--mode sync
```
clears the canvas and then writes the provided elements (good for “make canvas match this file”).
If you want stable ids across updates, keep ids in the exported JSON; if you want fresh ids, regenerate before importing.

将当前元素导出为JSON文件：

运行

node scripts/export-elements.cjs --out diagram.elements.json

使用批量创建方式导入元素（追加模式）：

运行

node scripts/import-elements.cjs --in diagram.elements.json --mode batch

使用同步方式导入元素（覆盖画布）：

运行

node scripts/import-elements.cjs --in diagram.elements.json --mode sync

注意事项：

```
--mode sync
```
模式会先清空画布，再写入提供的元素（适用于“让画布与文件内容保持一致”的场景）。
如果希望在更新过程中保持id稳定，请保留导出JSON中的id；如果需要新的id，请在导入前重新生成。

Workflow: CRUD Smoke Test (Create → Update → Delete)

工作流：CRUD冒烟测试（创建→更新→删除）

Clear:
- ```
node scripts/clear-canvas.cjs
```
Create a large visible rectangle + label:
- Use
```
node scripts/create-element.cjs
```
  twice (rectangle + text).
Update:
- Move the rectangle with
```
node scripts/update-element.cjs
```
  .
Delete:
- Remove both with
```
node scripts/delete-element.cjs
```
  .

清空画布：
- 运行
```
node scripts/clear-canvas.cjs
```
创建一个大的可见矩形和标签：
- 运行两次
```
node scripts/create-element.cjs
```
  （分别创建矩形和文本）。
更新元素：
- 使用
```
node scripts/update-element.cjs
```
  移动矩形。
删除元素：
- 使用
```
node scripts/delete-element.cjs
```
  删除这两个元素。

References

参考资料

```
references/cheatsheet.md
```
: MCP tool list + REST API endpoints + payload shapes

```
references/cheatsheet.md
```
：MCP工具列表 + REST API端点 + 负载结构