edwingao28/excalidraw-toolkit/excalidraw

Excalidraw Diagram Generator (MCP Edition)

For an existing saved diagram, use the file workflow below. For a new diagram, use the live canvas workflow that follows it.

Edit an existing saved diagram

Load the installed scoped-edit skill when the user asks to modify a saved .excalidraw file, including recoloring or relabeling it. The project installation places it in .claude/skills/scoped-edit/SKILL.md for Claude Code or .agents/skills/scoped-edit/SKILL.md for Codex. Its generated command prefix records the absolute Node and CLI paths; keep those paths unchanged.

Follow that skill's inspect → supported request → edited copy → receipt and PNG inspection workflow. inspect determines the available operations and target restrictions. Report missing installation or an unsupported operation explicitly. Preserve the saved scene and its original bytes; canvas clearing or regeneration does not implement a scoped edit. The remaining steps apply to new live diagrams.

Mental Model

You are placing shapes on a 2D canvas and drawing arrows between them.

(0,0) ────────── x increases ──────────►
  │
  │   ┌──────────┐      ┌──────────┐
  │   │  Box A   │─────►│  Box B   │
  │   └──────────┘      └──────────┘
  │         │
  y         ▼
  increases ┌──────────┐
  │         │  Box C   │
  ▼         └──────────┘

Everything is (x, y, width, height). That's it.

The 5 Tools You Actually Need

Other useful tools: describe_scene (text description of canvas), create_from_mermaid (quick diagram from Mermaid syntax), export_scene (save as .excalidraw JSON file), set_viewport (zoom/pan to fit), export_to_excalidraw_url (shareable link).

How Shapes Work

A shape has: type, position (x, y), size (width, height), colors, and label text.

{
  "type": "rectangle",
  "id": "my-box",
  "x": 100,
  "y": 100,
  "width": 180,
  "height": 70,
  "backgroundColor": "#a5d8ff",
  "strokeColor": "#1971c2",
  "roughness": 0,
  "text": "My Service\nPort 8080"
}

Key points:

• text puts a label directly inside the shape (MCP handles the binding for you)
• roughness: 0 = clean lines. roughness: 1 = hand-drawn look.
• Use \n for multi-line labels
• Shapes: rectangle, ellipse, diamond, text (standalone)

How Arrows Work

New arrows connect shapes by ID. The MCP creation helper computes endpoint positions; inspect the resulting geometry and screenshot before considering the connection complete.

{
  "type": "arrow",
  "x": 0,
  "y": 0,
  "startElementId": "my-box",
  "endElementId": "other-box",
  "strokeColor": "#1971c2",
  "text": "HTTP"
}

Key points:

• startElementId / endElementId = the id of the shape to connect to
• Supply the endpoint shape IDs and the coordinates required by the installed tool schema.
• Binding references alone do not guarantee rerouting after a shape moves. Check arrow points, bound labels, and the rendered result after any geometry change.
• text adds a label on the arrow
• strokeStyle: "dashed" = async/optional flows. "dotted" = weak dependency.
• startArrowhead / endArrowhead = "arrow", "dot", "triangle", "bar", or null

Step-by-Step Workflow

Step 1: Understand What to Draw

Read the codebase. Identify:

• Components (services, databases, APIs, queues, frontends)
• Connections (which components talk to which, and how)
• Layers (group related components into rows or zones)

Record source paths and relevant line ranges or symbols for code-derived components and connections. Distinguish imports, observed call sites, and assumptions; an import or valid source reference alone does not prove a runtime interaction. State unresolved connections and the inspected scope. Proceed with a clear diagram request; ask only when a material ambiguity prevents selecting the content or target.

When a sample diagram is provided (ASCII art, text mockup, screenshot, etc.):

• Preserve ALL text and detail from the sample by default. Do not simplify, summarize, or omit labels, annotations, bullet points, or sublabels present in the sample.
• Extract every node's full text (titles, subtitles, tool names, metrics, details) and reproduce it verbatim in shape labels using \n for multiline.
• Preserve section headers, status annotations (e.g. "Fail = Stop & Notify"), and arrow labels exactly as written.
• Size boxes large enough to fit the full text (increase height/width beyond defaults as needed).
• The sample is the source of truth for content — you may improve layout, colors, and styling, but never drop information.

Step 2: Read the Design Guide

mcp__excalidraw__read_diagram_guide()

This returns the color palette, sizing rules, and layout best practices. Use it.

Step 3: Inspect the Current Canvas

Call query_elements and get_canvas_screenshot before creating elements. Record existing IDs and choose an empty region for the new diagram. Use fresh IDs for this request and preserve unrelated elements.

clear_canvas replaces the entire current scene. Use it only when the user explicitly requests that replacement, then inspect the result before drawing. If the user asks to modify existing live content and its target is ambiguous, resolve the target first; the new-diagram recipe does not authorize replacing it.

Step 4: Plan Your Layout on Paper

Before calling any create tool, sketch the layout mentally:

Vertical flow (most common):
  Row 1 (y=0):    Zone backgrounds (large dashed rectangles)
  Row 2 (y=60):   Entry points / Users
  Row 3 (y=350):  Middle layer (APIs, services)
  Row 4 (y=650):  Data layer (databases, storage)
 
  Columns: x = 40, 440, 840  (spaced 400px apart for labeled arrows)
  Box size: 230 x 160 (standard)  |  200 x 120 (for decision diamonds)
  Spacing between rows: ~200px gap after accounting for box height
  Spacing between boxes in a row: 180px gap (for arrow labels)

Step 5: Create Everything in One Batch

Call batch_create_elements with the new diagram's elements, shapes before their arrows. The helper can resolve references to shapes in the same batch. Inspect the response for partial failures; query the request's IDs before retrying so successful elements are not duplicated.

Order of elements in the array:

1. Zone backgrounds (large dashed rectangles) — so they render behind everything
2. Shapes (rectangles, ellipses, diamonds) — with id set for arrow references
3. Arrows — using startElementId / endElementId
4. Standalone text labels (titles, annotations)

Step 6: Self-Critique Loop (automatic)

Inspect every generated diagram, including small diagrams. Check geometry and the actual screenshot before delivery, with at most two corrective passes.

6a. Record the affected elements

Limit corrections to the IDs created for this request and record their current values. A snapshot is optional only for a scene exclusively owned by this task. Whole-scene restore replaces other content too; use it only while exclusive ownership and the absence of intervening edits are established. Otherwise, repair the affected fields or report the remaining issue.

6b. Geometric validation (via query_elements)

mcp__excalidraw__query_elements({})

Check element positions and sizes programmatically:

6c. Visual validation (via screenshot)

mcp__excalidraw__get_canvas_screenshot()

Check for issues requiring visual judgment:

6d. Fix and re-check

Use supported tools to correct only this request's elements, then inspect the geometry and screenshot again. Keep stable IDs. A shape move may require corresponding bound-label and arrow updates; inspect those dependencies explicitly. Avoid delete-and-recreate repairs that silently discard bindings or metadata. If a safe correction is unavailable, retain the result and report the issue.

Constraints:

• Max 2 corrective passes. After 2, deliver the artifacts and state remaining problems. If screenshots cannot be inspected, report visual verification as incomplete.
• Only fix layout/visual issues. Do NOT change architectural content.
• Log what you fixed AND what remains unfixed.

Step 7: Present to User

mcp__excalidraw__set_viewport({ scrollToContent: true })
mcp__excalidraw__get_canvas_screenshot()

Show the final screenshot and summarize:

• Components and connections generated
• Auto-fixes applied during self-critique (if any)
• Remaining issues (if any)
• Available next actions (export, refine, drill-down)

Step 8: Export (if requested)

mcp__excalidraw__export_to_image({ format: "png", filePath: "/path/to/output.png" })
mcp__excalidraw__export_scene({ filePath: "/path/to/output.excalidraw" })
// Only when the user requests a shareable link:
mcp__excalidraw__export_to_excalidraw_url()

Complete Example: 3-Layer Architecture

This shows exactly what to pass to batch_create_elements:

{
  "elements": [
    // --- ZONE BACKGROUNDS (render behind everything) ---
    {
      "type": "rectangle", "id": "zone-frontend",
      "x": 0, "y": 0, "width": 500, "height": 160,
      "backgroundColor": "#e9ecef", "strokeColor": "#868e96",
      "strokeStyle": "dashed", "opacity": 40, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 10,
      "text": "Frontend Layer", "fontSize": 14, "strokeColor": "#868e96"
    },
    {
      "type": "rectangle", "id": "zone-backend",
      "x": 0, "y": 200, "width": 500, "height": 160,
      "backgroundColor": "#eebefa", "strokeColor": "#9c36b5",
      "strokeStyle": "dashed", "opacity": 30, "roughness": 0
    },
    {
      "type": "text", "x": 10, "y": 210,
      "text": "Backend Layer", "fontSize": 14, "strokeColor": "#9c36b5"
    },