Default
Hand-drawn outlines, Excalifont, no fill.
Skill explainer · yctimlin/mcp_excalidraw
Excalidraw
An agent draws on a live canvas, then screenshots its own work and fixes what it sees.
A skill, a CLI and an MCP server over one Excalidraw canvas. I read the skill and cheatsheet, ran the test suite, and drove every local CLI command against a private server. Pairing describe with screenshot is what makes this skill powerful.
774a70ccommit, 22 Oct 2026
v2.1.2package
26MCP tools
20CLI commands
3interfaces
5 suitestests pass
Who it is for
Agents drawing architecture or flow diagrams users will edit by hand.
What you get
An editable .excalidraw (or Obsidian .md) file, plus PNG or SVG.
How It Works
Plan The Grid, Draw, Screenshot, Fix
From SKILL.md.
1
Pick an interface. Three interfaces drive the same live canvas. Pick the first one that applies:
2
Plan. Plan your coordinate grid — map out tiers and x-positions before writing JSON.
3
Check every batch. After each add / apply / batch_create_elements, take a screenshot and check:
4
Say it out loud. If you find any issue: stop, fix it, re-screenshot, then continue.
5
No browser for checks. Screenshots and image exports render headless inside the canvas server, so you never need a browser tab to check your own work.
The CLI
20 Commands, Fixed Exit Codes
Descriptions are quoted from the cheatsheet. I ran each on a private port, except the two that publish or replace files.
Gallery
14 Renders
Renders from the earlier review, plus three from this run. Click to enlarge.
With the skill's styling
Cleaner, but the lettering is still Excalifont and the arrows still sketch.
Skill example, default
The 4-node load-balancer example from SKILL.md L148–159, as given.
Fill, default hachure
Same with a blue fill and no fillStyle: the sketchy hachure pattern.
Styled, light / dark
Solid pastels, roughness 0, helvetica requested; screenshot --dark for the pair.
Export → offline render
The styled scene exported to .excalidraw and rendered with render (no server). Labels come out in Helvetica here.
Anti-pattern 1: label on the zone
"VPC" label bound to the zone rectangle lands in the middle, under the arrow.
Anti-pattern 1, fixed
Free-standing text at the top of the zone.
Offline render of shorthand JSON
render on REST-shaped JSON (label/start/end) without the server: labels appear, arrows are not routed and sit at 0,0.
Repo demo.gif (frame 160 of 320)
The README demo: agent drawing on the live canvas.
Repo demo.gif (last frame)
Finished demo diagram.
This run: SKILL.md example
Headless screenshot from the canvas server, 8 elements.
This run: --dark
Same scene with --dark.
This run: offline render
render on the exported .excalidraw, no server.
The MCP Tools
26 Tools, One Per CLI Verb
Grouped as in the cheatsheet; parameters are shown as listed there.
What I Found Running It
Solid And Well Tested; A Few Sharp Edges
Run on a copy in /tmp with nice and timeout; the server ran on port 3917 and I stopped it by its own pid.
| Run | Result | Note |
|---|---|---|
| npm test (6 suites) | pass | stdio wire 5/5, local bind, 25 render checks, state, durable state, share URL. |
| CLI session | 16 commands | All behaved as documented. |
| mermaid with no tab | exit 4 | As documented. |
| export to a missing directory | exit 1 | ENOENT; no mkdir. |
Copy Headless verification
Screenshots render in the server with Excalidraw’s own renderer; the agent never needs a browser to see its work.
Copy Exit codes as an API
0 ok, 1 error, 2 usage, 3 canvas unreachable, 4 browser needed. Destructive clear needs --yes (exit 2 otherwise).
Copy Safe stop
stop checks /health identity and only signals its own server.
Gap Export does not create directories
A path inside a missing folder fails with ENOENT.
Gap Mermaid needs a browser tab
Conversion runs in the frontend, so headless agents cannot use it.
Cost Element counts drift
add and snapshot report 8 elements; export reports 12, because bound label text becomes separate elements. SKILL.md’s duplicate-text section covers the related auto-sync issue.
Cost share uploads
share sends an encrypted scene to excalidraw.com unless self-hosted URLs are set. I did not run it.
Build Your Own
What To Steal
One canvas, three interfaces. MCP, CLI and REST map 1:1.
Text plus pixels. describe for ids, screenshot for quality.
A written checklist. Seven checks after every batch.
Name the anti-patterns. Zone labels, cross-zone arrows and label spam, each with a fix.
Sources
Everything Here Is Checked
Each quote is compared with its source file at build time; the build fails on any mismatch.