Excalidraw MCP Diagramming

Create diagrams on a live Excalidraw canvas that renders in the browser and updates in real time. You are not generating a static file — you are painting onto a shared whiteboard through MCP tools. The canvas persists between calls, so what you put on it in one call is visible in the next screenshot.

When to Use

• The user asks to "create an excalidraw", "draw me a diagram", "make a flowchart", "visualise the system", or "diagram this architecture".
• The user wants an Excalidraw canvas output (not Draw.io / diagrams.net — use drawio-mcp-diagramming for that).
• The user wants to visualise an architecture, workflow, data flow, system design, mind map, or sequence diagram.
• The user asks to export a diagram to PNG, SVG, .excalidraw file, or a shareable URL.
• The user asks to update, change, or fix an existing Excalidraw diagram.

Required MCP Server

The excalidraw MCP server must be present in .vscode/mcp.json:

{
  "servers": {
    "excalidraw": {
      "type": "http",
      "url": "https://mcp.excalidraw.com"
    }
  }
}

If the MCP tools are not available, tell the user to add the server and reload VS Code, then stop.

Available Tools

Essential — use on every diagram:

Tool	Purpose	When
read_diagram_guide	Returns server-side colour palette and sizing rules	First call — before any elements
batch_create_elements	Creates multiple shapes and arrows atomically	Main workhorse
get_canvas_screenshot	Returns a photo of the current canvas	After every change — verify before continuing
clear_canvas	Wipes all content	Start of every new diagram
set_viewport	Scrolls and zooms to fit content	After creating elements

Secondary — use when needed:

Tool	When
create_from_mermaid	Quick drafts — 3–8 node sequential flows
update_element	Small corrections (position, colour, text)
export_to_image	User requests PNG or SVG file
export_scene	User requests editable .excalidraw file
export_to_excalidraw_url	User wants a shareable link
describe_scene	Audit what is currently on the canvas

---

Workflow

Step 1 — Choose the Creation Path

Mermaid path — use for simple sequential flows (3–8 nodes, no zones):

create_from_mermaid(
  mermaidDiagram="graph TD; A[Frontend] -->|REST| B[API]; B -->|SQL| C[DB]"
)

Then jump to Step 6 (screenshot). Skip Steps 2–5.

Batch path — use for everything else: layered architectures, data flows, hub-and-spoke, any diagram needing zones or colour-coded roles. Continue below.

Step 2 — Read the Design Guide

read_diagram_guide()

Retrieve the server's current colour palette and sizing rules. This call is mandatory — the values may differ from the defaults in this skill. The server guide takes precedence.

Step 3 — Clear and Confirm Empty

clear_canvas()
get_canvas_screenshot()   // must verify the canvas is truly empty

Previous diagrams leave ghost data even after clear_canvas. If any element is visible in the screenshot, call clear_canvas() again before proceeding. Do not skip this confirmation — ghost elements silently break arrow bindings on new diagrams.

Step 4 — Plan the Layout

Before writing any JSON, decide:

• Which pattern? — See references/canvas-patterns.md for coordinate templates. Load it now if you are unsure which pattern fits.
• Column spacing — Labeled arrows need ≥150px clear gap between boxes. Budget 440px column pitch (230px box + 210px gap) for labeled arrows.
• Row pitch — Allow ~350px per row (160px box height + 190px gap for arrows, labels, and breathing room).
• Zone positions — Calculate zone backgrounds before placing shapes. Zone background: y = row_y - 50, height = box_height + 100.

Sketch coordinates to paper or comments before writing the batch payload.

Step 5 — Create in One Batch

Call batch_create_elements with all elements in one payload. Arrow binding resolves at batch time — if the target shape and arrow are not in the same call, the arrow will not connect.

Element order within the elements array matters for render layering:

1. Zone backgrounds (large dashed rectangles, low opacity 25–40)
2. Shapes (rectangles, ellipses, diamonds) — assign unique id to each
3. Arrows — reference shapes by startElementId / endElementId
4. Standalone text (titles, zone labels, side annotations)

Step 6 — Screenshot and Verify

get_canvas_screenshot()

Inspect the image:

• Are all labels readable and unclipped by their containers?
• Do arrows land on the correct shapes?
• Are zone backgrounds behind their contents, not on top?
• Is there ≥150px of clear space around labeled arrows?
• Are connections logically correct?

Step 7 — Iterate and Refine

Load references/iterative-refinement.md if the user asks to change, fix, or update an existing diagram. Quick reference:

Audit first:

describe_scene()   // returns all element ids, types, labels, positions

Use this before any edit — you need the exact element id to target.

Small corrections (label text, colour, position):

update_element({ id: "box-1", text: "New Label" })
update_element({ id: "box-1", backgroundColor: "#b2f2bb" })

Then get_canvas_screenshot() to verify.

Shape replacement (size, shape type, structural change):

batch_create_elements([{ "type": "delete", "ids": "old-id" }, ...newShapes, ...newArrows])

Arrows bound to the deleted shape must also be deleted and recreated in the same batch — binding cannot be re-attached after the fact.

Decision rule:

Change	Method
Text / colour / opacity / position	update_element
Shape size, shape type	delete + redraw in one batch
Moving an arrow endpoint	delete + redraw arrow in one batch with target shape
Restructuring a zone (adding/removing shapes)	delete zone bg + all children + redraw all in one batch

Step 8 — Zoom to Fit

set_viewport({ scrollToContent: true })

Step 9 — Export (if requested)

// PNG or SVG
export_to_image({ format: "png", filePath: "/path/to/output.png" })

// Editable JSON file
export_scene({ filePath: "/path/to/output.excalidraw" })

// Shareable link — no file needed
export_to_excalidraw_url()

---

Typography Rules

Minimum font sizes — never go smaller. Labels that look correct in JSON are frequently unreadable in screenshots at display scale.

Context	Minimum fontSize	Notes
Shape labels / body text	16	Default for all labeled boxes
Diagram title	24	Standalone text above the diagram
Zone / section heading	16	Inside or above zone background
Secondary annotations	14	Data form notes, layer labels only — use sparingly
Absolute minimum	14	Never use below 14 under any circumstance

Camera scale warning: At XXL (1600×1200) the canvas renders at roughly 40% of original size in the chat panel. A fontSize: 14 label renders at ~5px — invisible. Use fontSize: 20+ for any label that must be readable without the user zooming in. When in doubt, go larger.

---

Shape Syntax

{
  "type": "rectangle",
  "id": "api-server",
  "x": 440, "y": 200,
  "width": 230, "height": 160,
  "backgroundColor": "#d0bfff",
  "strokeColor": "#7048e8",
  "roughness": 0,
  "text": "API Server\nExpress.js"
}

• roughness: 0 — crisp professional edges. roughness: 1 — hand-drawn feel.
• \n in text creates multi-line labels.
• Types: rectangle, ellipse, diamond, text (standalone).
• Zone backgrounds: same as rectangle but add strokeStyle: "dashed" and opacity: 30.

Arrow Syntax

{
  "type": "arrow",
  "x": 0, "y": 0,
  "startElementId": "api-server",
  "endElementId": "database",
  "strokeColor": "#2f9e44",
  "text": "SQL"
}

• x, y are approximate — binding to startElementId/endElementId overrides position. The server auto-routes to the nearest edges.
• startArrowhead / endArrowhead: "arrow", "dot", "bar", or null.
• strokeStyle: "dashed" — async or optional flows.
• strokeStyle: "dotted" — weak dependency.

---

Colour Quick Reference

Read references/color-palette.md for the full semantic colour table — load it when choosing colours for a new diagram type.

Role	Fill	Stroke
Frontend / UI	#a5d8ff	#1971c2
Backend / API	#d0bfff	#7048e8
Database	#b2f2bb	#2f9e44
Queue / Events	#fff3bf	#fab005
External / Third-party	#ffc9c9	#e03131
Zone background	#e9ecef + opacity:30	#868e96 dashed

Rule: Same architectural role → same colour pair. Limit diagrams to 3–4 fills. More colours add noise, not clarity.

---

Validation Checklist

Run through this before calling set_viewport. Fix any failures before finishing — they compound and are harder to fix after zooming out.

Arrow bindings

• Every arrow has both startElementId and endElementId referencing elements that exist in the same batch
• No arrow was created in a call before its target shapes
• Deleted shapes had their bound arrows deleted and redrawn in the same batch

Typography

• All shape labels use fontSize ≥ 16
• Diagram title uses fontSize ≥ 24
• No font smaller than 14 anywhere
• Multi-line labels (\n) have enough box height (≥ 60px per line)

Colour discipline

• No more than 4 distinct fill colours in the diagram
• Same architectural role uses the same fill/stroke pair throughout
• Zone backgrounds have opacity: 25–40 and strokeStyle: "dashed"

Layout and spacing

• Column gap between adjacent labeled boxes is ≥ 150px
• Zone backgrounds were placed in the batch before the shapes they contain
• Zone backgrounds do not hug inner boxes — ≥ 50px padding on all sides
• Title is horizontally centred over the diagram content

Viewport

• set_viewport({ scrollToContent: true }) called as the final step
• Camera size is one of the approved 4:3 ratios (400×300, 600×450, 800×600, 1200×900, 1600×1200)

---

Anti-Patterns (Quick Reference)

Anti-pattern	Why it causes problems
Skip screenshot after clear_canvas	Ghost elements silently corrupt new arrow bindings
Place arrows before their target shapes in a batch	Arrow IDs reference non-existent shapes — no binding
Column gap under 100px	Arrow labels bleed into adjacent shapes
Arrows without startElementId/endElementId	Arrow floats, doesn't update when shapes move
Skip set_viewport after creation	Diagram is off-screen and user sees a blank canvas
Zone backgrounds in a separate later batch	Zones render on top of shapes already on the canvas
More than 4 fill colours	Diagram becomes unreadable without a legend
fontSize below 16 on shape labels	Unreadable at XL/XXL camera scale
Editing a bound arrow with update_element	Binding is preserved but endpoints may drift — delete and redraw

---

Examples

"Draw me a 3-tier web architecture"

1. read_diagram_guide() — get colours
2. clear_canvas() → get_canvas_screenshot() — confirm empty
3. Plan: 3 zones (Frontend y=0, Backend y=360, Data y=720), 2 columns
4. batch_create_elements([zones..., shapes..., arrows..., titles...])
5. get_canvas_screenshot() — verify
6. set_viewport({ scrollToContent: true })

"Quick flowchart of user login"

1. create_from_mermaid("graph TD; A[Enter email] --> B[Verify] --> C[Dashboard]")
2. get_canvas_screenshot() — verify