
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 分