/excalidraw

name: excalidraw
description: Edit saved native Excalidraw diagrams with scoped file operations, or generate diagrams from specified components, a sample, or a description. Use for diagram edits, data flows, parameter traces, and PNG/SVG exports. For codebase discovery, use auto-diagram.

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

| Tool | What It Does | When to Use | |------|-------------|-------------| | `read_diagram_guide` | Returns color palette + sizing rules | **First call.** Read once, use throughout. | | `batch_create_elements` | Create many shapes + arrows at once | Main workhorse. Create your whole diagram in 1-2 calls. | | `get_canvas_screenshot` | Take a photo of the current canvas | **After every batch.** Verify it looks right. | | `clear_canvas` | Replace the current scene with an empty canvas | Only when the user explicitly requests replacement of the current canvas. | | `export_to_image` | Save as PNG or SVG | Final step if user wants an image file. |

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 u