Skip to main content
Glama

sketchdex

ci npm

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 install for the steps.

Or by hand:

Claude Code

claude mcp add --scope user sketchdex -- npx -y sketchdex

Codex

codex mcp add sketchdex -- npx -y sketchdex

Cursor

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, or all).

  • The sketchdex_docs tool 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 app

Opens 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

describe_scene

Structure, not pixels: bounds, counts, a rounded summary per element. Start here.

add_elements

Boxes, arrows, text, generated shapes (polygon, star, arc, capsule, path). label on a shape adds bound text; start/end on an arrow bind it.

update_elements

One id and the fields that change. The read-modify-write happens server-side, so a two-line edit costs two lines.

import_svg

Write an SVG, get hand-drawn editable elements grouped as one piece. The way to draw anything that has to look like something.

render_scene

A real canvas render as PNG, whole scene or a region, so the agent can look at its own work.

check_scene

Layout problems found by geometry: hidden text, overlapping labels, dangling arrows, strays.

snapshot_scene, list_history, restore_snapshot

The safety net. Every write snapshots the previous state first.

sketchdex_docs

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 .excalidraw file. Atomic writes (temp file, rename), deletes go to trash/, and index.json is 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>.excalidraw

Node 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 app

For 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/browser if 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, ⌘K opens 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 tools
add_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

    A3.6/5.0

    Scored across 19 tools

    Disambiguation4/5

    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).

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      8
      MIT