Excalidraw

Excalidraw

Author diagrams in an Excalidraw+ workspace through the official Excalidraw MCP server (https://api.excalidraw.com/api/v1/mcp).

Choosing a transport

1. Native MCP tools first. If this session exposes Excalidraw MCP tools (e.g. mcp__excalidraw__create_diagram, or excalidraw tools in Codex), use them directly.

2. Bundled CLI otherwise. If no native tools are available, use the zero-dependency CLI in this skill (Node ≥ 18):

   node scripts/excal.mjs tools                  # list tools
   node scripts/excal.mjs help <tool>            # print a tool's input schema
   node scripts/excal.mjs call <tool> --json '{"key":"value"}'
   

   Both paths hit the same server with the same tools — everything below applies to either. (CLI examples are shown; substitute native tool calls 1:1.)

Auth: the CLI reads EXCALIDRAW_API_KEY from the environment (raw sk-… or Bearer sk-… both work), falling back to ~/.config/excalidraw/api_key. If the key is missing the CLI prints setup instructions — relay them to the user; never paste keys into files that could be committed.

Core workflow

1. Classify the request against references/use-cases.md — it maps every Excalidraw use case (flowchart, architecture, sequence, data-flow, UML, Gantt, mind map, wireframe, presentation, roadmap, persona, brainstorm, Lean Canvas, SWOT, competitor analysis, game design, interview) to the right tool and layout recipe.
2. Read the matching format guide before your first content write — this is required by the server, not optional:
   • read_diagram_format — node/edge diagrams: architecture, flowcharts, workflows, swimlanes, dependency graphs, hierarchies, timelines
   • read_presentation_format — slide decks (one frame = one slide)
   • read_freeform_format — everything else: wireframes, personas, sticky-note boards, annotations, moodboards Never guess Excalidraw element fields, enum values, bindings, or frame behavior — the guides are authoritative and current.
3. Create the scene. create_scene requires name, pinned, and collectionId — get an id from list_collections (use the collection with "isDefault": true unless told otherwise).
4. Author the content:
   • Node/edge diagrams → create_diagram (semantic nodes + edges; automatic layout, elbow arrows, edge labels). Use edit_scene_content only for tweaks and layouts it can't express (swimlanes, timelines, Gantt, custom compositions).
   • Presentations → create_slide per slide, then fill each frame with edit_scene_content using the returned frameId and safe area; add_image for images; review with list_slides.
   • Freeform (wireframes, personas, brainstorms) → edit_scene_content directly.
5. Verify visually. take_screenshot (whole scene or one frame) and inspect the result before declaring done. Fix overlaps and spacing issues you see — don't ship a diagram you haven't looked at.
6. Hand back the link: https://app.excalidraw.com/s/<workspace>/<sceneId> (workspace and scene ids appear in tool responses).

Rules

• Do not invent IDs (scenes, collections, frames) — list or create first.
• Do not delete or overwrite scenes unless explicitly asked.
• Match Excalidraw's hand-drawn aesthetic: default fonts/roughness, a restrained palette (2–3 hues max), generous whitespace. Design conventions per diagram type live in references/use-cases.md.
• Scene content edits must use valid Excalidraw element format from the format guides (step 2) — invalid elements corrupt scenes.
• Tool catalog and pagination notes: references/api.md.