AgentSkillsCN

excalidraw-mcp

使用mcp-excalidraw-server（MCP工具 + 画布REST API）创建、编辑并导出实时Excalidraw图表。当智能体需要绘制或布局图表、将Mermaid转换为Excalidraw、查询/更新/删除元素，或从运行中的画布服务器（EXPRESS_SERVER_URL，默认http://localhost:3000）导出/导入元素时，即可触发该技能。

SKILL.md
--- frontmatter
name: excalidraw-mcp
description: 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).

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