yctimlin/mcp_excalidraw

MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.

這個專案是做什麼的

mcp-excalidraw-server 將本機 Excalidraw 畫布轉變為一個可程式化的工作台，供 AI 編碼代理（Claude Code、Cursor、Codex 等）操作。畫布完全在本機執行（Node ≥ 20，無需 API 金鑰），可透過以下三種方式存取：

CLI – npx -y mcp-excalidraw-server <command> – 一組基於 JSON 的命令，可自動啟動畫布、新增/更新/刪除元素、擷取螢幕截圖、匯出檔案等。
MCP 伺服器 – 一個暴露 26 個工具的 Model Context Protocol (MCP) stdio 伺服器，任何相容 MCP 的用戶端都可以直接呼叫繪圖操作。
REST API – 面向 LangChain 等框架的普通 HTTP/WebSocket 端點。

最終結果是一個即時、可編輯的圖表，代理可以（透過 describe 或螢幕截圖）檢查它，逐元素進行修改，最後將其匯出為 .excalidraw 檔案，該檔案可以放在原始碼旁邊或 Obsidian 庫中。

適合誰使用

編碼助手 – 需要在開發工作流程中產生架構圖、流程圖或 UI 線框圖的工具。
團隊 – 希望將圖表檔案與程式碼一起進行版本控制的團隊（例如，將 .excalidraw 檔案提交到 Git）。
Obsidian 使用者 – 希望將圖表保存在庫中並保持完全可編輯性的使用者。
建置自訂 AI 代理工具鏈的人 – 建置可以呼叫 MCP 工具或 REST API 的工具鏈的開發者。

主要功能（摘自 README）

功能	說明
本機畫布伺服器	在 `http://127.0.0.1:3000` 上執行 Excalidraw Web UI，並提供即時 WebSocket 同步。無需外部服務。
CLI 優先設計	所有功能都作為可組合的命令（`add`、`apply`、`query`、`screenshot`、`export`、`mermaid`、`snapshot`、`arrange`、`share` 等）公開。JSON 輸出到標準輸出，結束代碼表示成功/失敗。
MCP 整合	實作 MCP 協定修訂版 `2026-07-28`。26 個工具讓任何 MCP 用戶端（Claude Desktop、Cursor、Codex CLI、Antigravity 等）都能透過 stdio 操作畫布。
REST API	面向 LangChain 和自訂指令碼的簡單 HTTP 端點。
元素級 CRUD	可以建立、讀取、更新、刪除單一形狀、箭頭、文字、群組、鎖定等。
迭代最佳化	代理可以 `describe` 場景、拍攝 `screenshot`、調整佈局，並重複直到圖表完成。
匯出 / 匯入	匯出為原生 `.excalidraw` JSON 或 Obsidian 相容的 `.excalidraw.md`。支援匯入兩種格式，包括壓縮檔案。
確定性匯出	ID、種子和鍵的順序是穩定的，因此未變更的圖表會產生相同的檔案，不會產生雜亂的 Git 差異。
Mermaid 轉換	貼上 Mermaid 語法，產生的圖表會合併到現有畫布中。
視埠控制	縮放、平移或適配所選元素的命令。
分享	可選地將加密上傳到 `excalidraw.com` 以產生可分享的 URL。
Docker 映像	用於輕鬆部署的預建置容器（`ghcr.io/yctimlin/mcp_excalidraw`）。
代理技能包	一個可攜帶的技能（`skills/excalidraw-skill/`），可透過單一 `install-skill` 命令安裝到代理的技能目錄中。
零設定自動啟動	CLI 命令和 MCP 伺服器會在畫布未執行時自動啟動（可透過 `EXCALIDRAW_NO_AUTOSTART=1` 停用）。

快速開始

# 安裝並啟動畫布（在第一個繪圖命令時自動啟動）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # 可選 – 螢幕截圖/Mermaid 需要

# 新增兩個框和一個箭頭（透過標準輸入傳遞 JSON）
echo '[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# 讓代理檢視圖表
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# 為版本控制匯出
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

相同的命令也可以從相容 MCP 的用戶端或透過 HTTP 呼叫。

已知限制 / 未解決問題（摘自 README）

伺服器預設僅繫結到 127.0.0.1。要對外暴露，使用者需要自行設定防火牆或反向代理 – 沒有內建驗證。
某些操作（例如 screenshot、mermaid 轉換）依賴用戶端的 Excalidraw UI，因此需要開啟瀏覽器標籤頁。
README 中有幾個「已知問題 / TODO」部分，但沒有列出具體錯誤；請查看問題追蹤器以取得最新狀態。

維護者

該儲存庫由 yctimlin 所有，並以 mcp-excalidraw-server 發佈在 npm 上（MIT 授權）。持續整合會在每次推送時執行測試並建置 Docker 映像。

TL;DR

mcp-excalidraw-server 為 AI 編碼代理提供了一個真正可編輯的繪圖表面，可以透過程式設計方式控制。它透過簡單的 CLI、MCP stdio 伺服器或 REST API 工作，並將圖表儲存為版本控制的 .excalidraw 檔案 – 在 LLM 產生的架構想法和具體、可編輯的圖表之間架起了一座實用的橋樑。