
Sketchdex
io.github.lucasr1bPublished by GitHub account lucasr1bv0.1.2Updated Oct 24, 2026
An MCP server that lets AI agents draw hand-drawn Excalidraw diagrams as files on your machine.
Overview
Lets an AI assistant draw hand-drawn Excalidraw diagrams and save them as .excalidraw files in a local folder.
- What you can do
- Describe a scene's structure, bounds and element counts
- Add and update elements: boxes, arrows, text, generated shapes, labels and bindings
- Import SVG artwork as editable hand-drawn elements
- Render a scene or region to PNG and check layout problems by geometry
- Snapshot, list and restore history so every write can be undone
- Read the bundled manual by topic for setup and troubleshooting
- When to use it
- Useful when you want an assistant to explain something visually — architecture, flows, brainstorms — and leave you with editable Excalidraw files you can keep working on in the bundled app or on excalidraw.com.
- Requirements
- Runs locally over stdio via npx, needing Node 20 or newer. Rendering to PNG needs a Chromium-based browser (Chrome, Chromium, Edge or Brave), configurable with SKETCHDEX_BROWSER. Scenes go to ~/Documents/sketchdex by default, changeable with --vault or SKETCHDEX_VAULT. No account or API key.
Installation
In SourceWeft
- Open Sketchdex in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
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
Codex
Cursor
Add to Cursor, or in ~/.cursor/mcp.json:
VS Code
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.
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
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:
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.
Node API
Same implementation as the MCP and REST surfaces. Works with the app closed.
Development
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/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.
Source: README.md at commit 5dd4b7b
Tools
0Version history
1- v0.1.2LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts