yctimlin/mcp_excalidraw

Overview

This skill is a programmatic canvas toolkit for creating, editing, and refining Excalidraw diagrams with real-time canvas sync. It supports element-level CRUD, alignment, grouping, duplication, snapshots, import/export (.excalidraw, PNG, SVG), Mermaid conversion, and iterative refinement using visual screenshots. A running canvas server (EXPRESS_SERVER_URL, default http://localhost:3000) or MCP server is required for full functionality.

How this skill works

The skill detects the best connection mode: MCP tools first (preferred), then the REST API as a fallback, and guides setup if neither is available. It issues batch element operations, element updates, snapshots, exports, and screenshots, and uses a mandatory quality-check feedback loop after every iteration so the agent can see its own changes and fix layout/text/arrow issues. REST and MCP modes use slightly different payload formats (label/arrow binding differences), which the skill handles or documents for correctness.

When to use it

• Programmatically draw or lay out diagrams on a live Excalidraw canvas.
• Iteratively refine diagrams with screenshots and automated quality checks until layout and readability pass.
• Export or import diagrams as .excalidraw, PNG, or SVG for sharing or publishing.
• Save and restore canvas snapshots before risky edits or experiments.
• Perform element-level operations: create, read, update, delete, align, group, duplicate, lock/unlock.

Best practices

• Always run Step 0 to detect MCP vs REST mode before issuing requests.
• Follow the Quality Checklist after every batch: check truncation, overlap, arrow routing, spacing, and readability before continuing.
• When using REST API, send labels as {"label":{"text":"..."}} and bind arrows with {"start":{"id":"..."},"end":{"id":"..."}}.
• Size shapes to prevent truncation: width = max(160, textLength*9); height = 60/80/100 for 1/2/3 lines; keep font >=16 for body and >=20 for titles.
• Plan a coordinate grid (tiers and side panels) before creating elements to avoid overlap and ensure consistent spacing.

Example use cases

• Generate architecture diagrams from code or metadata, iteratively improving layout until quality checks pass.
• Convert Mermaid flowcharts into editable Excalidraw diagrams for visual refinement and annotation.
• Automate export of system diagrams to PNG/SVG for documentation and slide decks.
• Snapshot a canvas before a risky refactor, make changes programmatically, evaluate with screenshots, and restore if needed.
• Duplicate and adjust service blocks to quickly create uniform microservice layouts with proper spacing.