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

12installs
Sourceyctimlin/mcp_excalidraw
Added on

NPX Install

npx skill4agent add yctimlin/mcp_excalidraw excalidraw-mcp

Tags

Translated version includes tags in frontmatter
excalidraw-mcpdiagram-editingcanvas-apiworkflow-automationmcp-tools

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)

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

Workflow: Refine An Existing Diagram

  1. Discover what’s already there:
    • Prefer 
      get_resource
      with 
      resource: "elements"
      or 
      query_elements
      .
  2. Identify targets by stable signals (id, type, label text), not by exact x/y.
  3. Update with 
    update_element
    (move/resize/colors/text) or delete with 
    delete_element
    .
  4. 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)

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

References

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