sketchdex
Draws hand-drawn Excalidraw diagrams, with scenes stored as real .excalidraw files that can be opened and further edited in Excalidraw (the bundled library app or excalidraw.com). Built on the official @excalidraw/excalidraw canvas, it lets an agent create and modify elements (boxes, arrows, text, generated shapes like polygons and stars, imported SVG), read its own work back structurally (describe_scene, check_scene) or visually (render_scene as PNG), and undo its writes via snapshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sketchdex draw me how a web request flows through a server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sketchdex
Give your agent a whiteboard. sketchdex.dev
Sketchdex is an MCP server that lets Claude, Codex, Cursor and any other MCP
client draw hand-drawn Excalidraw diagrams while it explains something. Scenes
are real .excalidraw files in a folder on your machine. The agent can draw,
look at what it drew, and fix it; you can open the result in the bundled
library app or on excalidraw.com and keep editing.
Built on the official @excalidraw/excalidraw package, so the canvas is the
real thing. MIT.
Install
Needs Node 20 or newer. Rendering (render_scene) needs a Chromium-based
browser on the machine: Chrome, Chromium, Edge or Brave. Everything else works
without one.
The quickest way is to let the agent you already have do it. Paste this into any agent that can run commands:
install the sketchdex mcp server for me. run
npx -y sketchdex docs installfor the steps.
Or by hand:
Claude Code
claude mcp add --scope user sketchdex -- npx -y sketchdexCodex
codex mcp add sketchdex -- npx -y sketchdexCursor
Add to Cursor, or in ~/.cursor/mcp.json:
{
"mcpServers": {
"sketchdex": {
"command": "npx",
"args": ["-y", "sketchdex"]
}
}
}VS Code
code --add-mcp '{"name":"sketchdex","command":"npx","args":["-y","sketchdex"]}'Claude Desktop, Windsurf, Gemini CLI, anything else takes the same
mcpServers block as Cursor, or the command npx -y sketchdex as a stdio
server. npx -y sketchdex docs install has the exact file for each.
Then, in a session: draw me how the event loop works using sketchdex.
Scenes are saved to ~/Documents/sketchdex. Point them somewhere else with
--vault /path/to/folder after the package name, or SKETCHDEX_VAULT in the
server's environment. An iCloud or Dropbox folder works.
Related MCP server: excalidraw-mcp
Docs, for the agent
The manual ships inside the package so an agent can answer setup questions and fix problems without anyone reading a page:
npx -y sketchdex docs [topic]prints it (topics:install,vault,app,rendering,tools,drawing,troubleshooting, orall).The
sketchdex_docstool returns the same text once the server is connected, and the server instructions tell the agent to use it for anything about setup or errors.The same topics are MCP resources at
sketchdex://docs/<topic>.
The app
npx sketchdex appOpens the library in your browser: a grid of scenes with live previews,
search, pin, rename, duplicate, import; a full Excalidraw editor for each; a
⌥K switcher; and a History sidebar showing every agent write with the
label the agent gave it, so you can preview, keep or revert each one. The app
notices agent writes as they happen.
The same process serves the tools over HTTP at POST /mcp and as plain REST at
POST /api/agent/:op, localhost only.
What the agent gets
Nineteen tools over stdio. The ones that matter:
Tool | Does |
| Structure, not pixels: bounds, counts, a rounded summary per element. Start here. |
| Boxes, arrows, text, generated shapes ( |
| One id and the fields that change. The read-modify-write happens server-side, so a two-line edit costs two lines. |
| Write an SVG, get hand-drawn editable elements grouped as one piece. The way to draw anything that has to look like something. |
| A real canvas render as PNG, whole scene or a region, so the agent can look at its own work. |
| Layout problems found by geometry: hidden text, overlapping labels, dangling arrows, strays. |
| The safety net. Every write snapshots the previous state first. |
| The manual by topic, so the agent can answer setup questions and fix errors itself. |
The full manual the agent reads is BRIEF.md: the element format,
the hand-drawn contract (roughness, sparse anchors, flat colour, no clip-art),
paper and ink rules, and the things that will bite.
How it holds up
Files are the truth. Every scene is a plain
.excalidrawfile. Atomic writes (temp file, rename), deletes go totrash/, andindex.jsonis a cache the server rebuilds from the files if it is lost.Every agent write is undoable. Snapshots are gzipped, capped at 20 per scene, images excluded, and never expire on their own.
Deltas, not rewrites. Edits you make in the editor while the agent works survive: writes carry a revision token and conflicting saves are merged.
Local only. No account, no upload, no telemetry. The server binds 127.0.0.1.
~/Documents/sketchdex/
├── index.json names, timestamps, pins (a cache, not the truth)
├── scenes/<id>.excalidraw the scene itself, real Excalidraw format
├── thumbs/<id>.svg library previews
├── history/<id>/ snapshots taken before agent writes, gzipped
└── trash/<stamp>-<id>.excalidrawNode API
import { createAgentApi } from "sketchdex";
const api = createAgentApi(); // or createAgentApi("/path/to/vault")
await api.describeScene("Brain Dump");Same implementation as the MCP and REST surfaces. Works with the app closed.
Development
git clone https://github.com/lucasr1b/sketchdex
cd sketchdex
npm install # also retunes Excalidraw's colour picker for dark paper
npm run dev # app + API + HTTP MCP on http://localhost:5173
npm run build # dist/, which the CLI and the render page need
node bin/sketchdex.js appFor an MCP client pointed at a checkout, use node /path/to/sketchdex/mcp/server.js
as the command. In a checkout the server hot-reloads its worker when a file
under server/ or mcp/ changes, so edits are live on the next tool call
without restarting the client.
npm run lint, npx tsc -p tsconfig.app.json --noEmit and npm test before
committing. The test packs the package, installs it into a clean project and
drives it through a real MCP client, including a render; CI runs it on macOS,
Linux and Windows.
AGENTS.md maps the codebase and the rules that must survive
edits. There is also a macOS desktop shell: npm run electron:dev.
Notes
New scenes are dark paper (
#121212) and nothing is ever colour-inverted: the canvas, thumbnails and renders show every hex exactly as written. Paper colour is per scene (viewBackgroundColor).The first render on a fresh install takes a few seconds while the browser starts; after that about a second and a half.
Set
SKETCHDEX_BROWSER=/path/to/browserif the browser is somewhere unusual.The server only answers requests whose Host is localhost and refuses cross-site writes, so a web page open in your browser cannot touch the vault. It still binds a plain local port: anything running as you on the same machine can reach it, which is the point.
In the app,
⌘Kopens the scene switcher, which shadows Excalidraw's own "add link" shortcut; use the context menu for links.The app registers a small service worker (for install-as-app). It does no caching, but if you run another project on the same port later it will show up in that project's devtools until you unregister it.
Available Tools
19 toolsadd_elementsA
Append elements to a scene, leaving everything already there untouched. The usual way to draw something new.
Inputs: label (required), scene (required), elements (required).
check_sceneA
Find layout problems by geometry instead of by looking: text hidden behind a filled shape drawn after it, captions running past the panel they sit in, labels too tall for their container, zero-size elements, broken arrow bindings, strays parked far off, exact duplicates. Each finding carries the element ids, so the fix is one update_elements call. Run it after a batch of drawing - it is far cheaper than a render and catches what a render would only show you if you looked closely.
Inputs: scene (required), limit.
create_sceneB
Make a new scene, optionally with its starting elements.
Inputs: name, elements.
delete_elementsC
Remove elements by id.
Inputs: ids (required), label (required), scene (required).
describe_sceneA
What is on a scene, as structure rather than pixels: counts by type, overall bounds, and a rounded summary of each element with its id, position, size, text and bindings. Cheaper than read_scene and usually enough to plan an edit.
Inputs: scene (required), type, limit.
import_svgA
Draw by writing SVG. THE way to draw anything that has to look like something: a character, creature, object, vehicle, logo, illustration. This is what produces good figures; stacking shapes with add_elements does not.
The result is hand-drawn, not pasted: every path becomes a real editable Excalidraw element (grouped as one piece), curves are re-spaced to hand-sized strokes and drawn with the sketchy pen, // become native shapes. Write the SVG for SHAPE, PROPORTION and COLOUR and let the canvas supply the pen - do not fake wobble or hatching in the SVG.
A recipe that works for a figure:
viewBox about 300 x 600 for a standing figure; import at width 350-450.
ONE closed path per body region - torso, each leg, each arm - tapered like a real limb (forearm ~60% of the upper arm, calf into a narrow ankle), plus head, hands, feet. Let them overlap; later paths draw on top. Then detail as separate strokes OVER the silhouette: plates, seams, webbing, a knee line. A few, not many.
Every shape: fill=<vibrant, character-accurate hex> stroke=<the scene ink from describe_scene, or a deep shade of the fill> stroke-width 2 to 2.5. Filled shapes with no stroke read as flat.
Flat colour, no shading. One solid fill per part; a darker part is a darker hex, not a hatched overlay or a shadow shape. The sketchy outline carries the drawing - texture on top of it looks overworked.
Proportion from a rule: 7-8 heads tall for heroic, 5-6 for stylised. Head first, derive the rest.
Then render_scene and LOOK; fix what is off. The first pass is usually mis-proportioned, the second is right.
Supported: path (all commands), rect, circle, ellipse, line, polyline, polygon, g, transform, /class, /, presentation attributes, text. viewBox honoured exactly. Gradients flatten to their first stop; pass holeColor to punch compound-path holes.
Inputs: svg (required), label (required), scene (required), x, +10 more.
list_historyB
Snapshots held for a scene, newest first.
Inputs: scene (required).
list_scenesA
Every scene in the vault with its id, name, element count and last-edited time. Start here.
Inputs: no named parameters.
move_elementsA
Shift a set of elements by dx, dy in one write, keeping everything else about them. Select by ids, groupIds (an import_svg piece), a region box, or any mix. A container's label always moves with it, and an arrow bound to something that moves keeps that end attached (include the arrow itself to move it whole). Returns the new bounds of what moved.
Inputs: label (required), scene (required), dx, dy, +3 more.
read_elementsA
Full, unabridged elements, filtered down to the ones you need. Use this rather than read_scene when editing a few things in a busy scene.
Inputs: scene (required), ids, type, limit, +2 more.
read_sceneA
The whole scene exactly as stored, plus the path to the .excalidraw file on disk. Large scenes run to thousands of elements, so prefer describe_scene or read_elements unless you genuinely need everything. The path is there for edits no tool here covers - take a snapshot first if you use it.
Inputs: scene (required), includeFiles.
render_sceneA
A PNG of the scene as it actually renders, so you can look at what you drew. Use it to check your own work - proportions, overlaps, whether the thing reads as the thing. Always written to a file as well as returned. A tall or wide page (long edge more than about twice the short one, and too big to fit at the asked size) comes back as a few tiles cut along its length, each with the scene box it shows, so a whole board is readable in one call; a region renders just that box, which is the way to look closely at one part. When an image is too big to travel inline you get a downscaled preview plus the file path.
Inputs: scene (required), ids, scale, tiles, +3 more.
replace_sceneA
Replace a scene's entire contents. Destructive by design - the previous state is snapshotted, but prefer add_elements or update_elements when you only mean to change part of it.
Inputs: label (required), scene (required), elements (required).
restore_snapshotB
Put a snapshot back on the canvas. This is itself snapshotted, so reverting a revert is possible.
Inputs: scene (required), snapshot (required).
set_backgroundA
Set the paper: the scene's real background colour, shown exactly as given (never inverted). The default pen for hand drawing follows it, so the next stroke in the app is visible. Elements already drawn keep their colours - recolour their ink yourself if you flip a scene from light to dark or back. New scenes start on dark paper (#121212).
Inputs: color (required), label (required), scene (required).
sketchdex_docsA
The manual, for answering the user's questions and fixing problems without guessing: install on any client, where scenes are stored and how to move the vault, the library app, what rendering needs, every tool, the drawing contract, and troubleshooting for the errors that come up. No topic returns the index.
Inputs: topic.
sketchdex_infoA
Version of this server, where it is running from, which vault it is using, and how long this process has been alive. Use it to confirm you are talking to the build you think you are.
Inputs: no named parameters.
snapshot_sceneA
Stash the current state without changing anything, so it can be restored from the history sidebar. Do this before editing a .excalidraw file directly with your own file tools - every other tool here snapshots on its own.
Inputs: label (required), scene (required).
update_elementsA
Change named fields on existing elements. Send only what changes - {id, x: 40} moves one box and leaves its other 25 fields alone. Pass a list in elements, each carrying its id, or use ids + patch to apply one change across many.
Inputs: label (required), scene (required), ids, patch, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Most tools target clear and distinct operations (add vs update vs delete vs move vs replace elements). There is some overlap in the reading surface (describe_scene, read_elements, read_scene) and between move_elements and update_elements, but the descriptions explicitly clarify when to use each (cheaper summary vs filtered vs full; move adds group/region selection).
Nearly all tools follow a clean snake_case verb_noun pattern (list_scenes, create_scene, add_elements, restore_snapshot). The only deviations are the namespace-style sketchdex_info and sketchdex_docs, which is a mild but coherent exception for meta tools.
19 tools is on the heavier side but justified for a full drawing/editing domain covering scenes, elements, SVG import, rendering, layout checking, background, docs and history. Each tool occupies a distinct role, though it sits near the upper bound of comfortable scoping.
The surface is broad: scene and element CRUD, SVG import, geometric validation, rendering, background control, snapshots and history restoration. Minor gaps exist (no delete_scene or group/ungroup tool), but agents can work around these with replace_scene and groupIds.
Maintenance
Related MCP Connectors
A shared Excalidraw board that people and agents draw on together
Real-time collaborative whiteboard — AI agents and humans edit the same board live over MCP.
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables users to create and interact with hand-drawn Excalidraw diagrams featuring smooth viewport camera control and interactive fullscreen editing. It uses the MCP Apps extension to render collaborative virtual whiteboards directly within supported AI chat interfaces.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create and manipulate live visual diagrams on an Excalidraw canvas in real-time via MCP tools.37 PyPI15BSD 3-Clause
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to collaboratively draw and annotate Excalidraw diagrams in real-time via MCP tools, synced to a browser canvas.11Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, modify, and share diagrams on a live Excalidraw canvas through MCP tools, supporting shapes, text, arrows, batch operations, and export to shareable links with images.8MIT