thomast1906/excalidraw-mcp-diagramming

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