
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.
概览
让 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 密钥。
安装
在 SourceWeft 中
- 打开 控制台中的 Sketchdex,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
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.
来源:README.md,提交 5dd4b7b
工具
0版本历史
1- v0.1.2最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分