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