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 分