excalidraw-mcp

Original：🇺🇸 English

Translated

7 scripts

Create, edit, and export live Excalidraw diagrams using mcp-excalidraw-server (MCP tools + canvas REST API). Use when an agent needs to draw/lay out diagrams, convert Mermaid to Excalidraw, query/update/delete elements, or export/import elements from a running canvas server (EXPRESS_SERVER_URL, default http://localhost:3000).

1installs

Sourceyctimlin/mcp_excalidraw

Added on2026-02-07

NPX Install

npx skill4agent add yctimlin/mcp_excalidraw excalidraw-mcp

SKILL.md Content

View Translation Comparison →

Excalidraw MCP

Overview

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

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
```
.

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.

Workflow: Refine An Existing Diagram

Discover what’s already there:

Prefer

get_resource

with

resource: "elements"

or

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).

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.

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

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
```
  .

References

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