Sketchdex

io.github.lucasr1b由 GitHub 账号 lucasr1b 发布v0.1.2更新于 Oct 24, 2026

An MCP server that lets AI agents draw hand-drawn Excalidraw diagrams as files on your machine.

已验证STDIO仅桌面文件与存储媒体与设计

概览

AI 生成的概览

让 AI 助手绘制手绘风格的 Excalidraw 图表,并以 .excalidraw 文件保存到本机文件夹。

可以做什么
  • 描述场景结构、边界与元素数量
  • 添加和修改元素:方框、箭头、文本、生成图形、标签与绑定
  • 导入 SVG 图形并转换为可编辑的手绘元素
  • 将整个场景或局部渲染为 PNG,并按几何检查排版问题
  • 创建快照、列出历史并恢复,使每次写入都可撤销
  • 按主题读取内置手册,用于安装与排错
适用场景
适合让助手用图示讲解内容,例如架构、流程或头脑风暴,并留下可在内置应用或 excalidraw.com 中继续编辑的 Excalidraw 文件。
运行要求
通过 npx 以 stdio 在本机运行,需要 Node 20 或更高版本。渲染 PNG 需要 Chromium 内核浏览器(Chrome、Chromium、Edge 或 Brave),可用 SKETCHDEX_BROWSER 指定。场景默认保存在 ~/Documents/sketchdex,可用 --vault 或 SKETCHDEX_VAULT 更改。无需账号或 API 密钥。
安装前请注意
助手会写入、修改和删除该文件夹中的文件,不过写入前会创建快照,删除的文件会进入 trash。应用与 HTTP 接口绑定普通本地端口,以你的身份运行的同机程序都能访问该目录。若把 SKETCHDEX_VAULT 指向同步文件夹,需接受这些文件被同步到第三方。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Sketchdex,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

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

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

Codex

bash
codex mcp add sketchdex -- npx -y sketchdex

Cursor

Add to Cursor, or in ~/.cursor/mcp.json:

json
{  "mcpServers": {    "sketchdex": {      "command": "npx",      "args": ["-y", "sketchdex"]    }  }}

VS Code

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

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

bash
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:

ToolDoes
describe_sceneStructure, not pixels: bounds, counts, a rounded summary per element. Start here.
add_elementsBoxes, arrows, text, generated shapes (polygon, star, arc, capsule, path). label on a shape adds bound text; start/end on an arrow bind it.
update_elementsOne id and the fields that change. The read-modify-write happens server-side, so a two-line edit costs two lines.
import_svgWrite an SVG, get hand-drawn editable elements grouped as one piece. The way to draw anything that has to look like something.
render_sceneA real canvas render as PNG, whole scene or a region, so the agent can look at its own work.
check_sceneLayout problems found by geometry: hidden text, overlapping labels, dangling arrows, strays.
snapshot_scene, list_history, restore_snapshotThe safety net. Every write snapshots the previous state first.
sketchdex_docsThe 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

js
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

bash
git clone https://github.com/lucasr1b/sketchdexcd sketchdexnpm install          # also retunes Excalidraw's colour picker for dark papernpm run dev          # app + API + HTTP MCP on http://localhost:5173npm run build        # dist/, which the CLI and the render page neednode 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.

来源:README.md,提交 5dd4b7b

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.1.2最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分