Excalidraw 透過 MCP 是做什麼的？
只要說「使用 Excalidraw MCP」，就應該能產出複雜的圖表，即時繪製並儲存在正確的位置。這個技能就是為了確保這一點。
最關鍵的一件事
create_view 的元素格式是骨架，而不是磁碟上的結構。形狀的 label 是骨架專屬的語法糖。Excalidraw 的畫布渲染器對矩形／橢圓／菱形沒有文字分支——容器文字僅透過 boundElements → containerId 繪製。因此，將 create_view 的 JSON 直接貼入 .excalidraw 檔案會產生空白方塊。這就是 scripts/excalidraw_build.py 存在的原因：在骨架中撰寫一次，即可同時獲得即時渲染與正確的檔案。
第二個重點：手寫圖表不會隨著規模增大而逐漸劣化——它們會因為不規則而失敗。在實際生成的場景中，重複佈局公式產生的元素缺陷率為 0.00，而單獨客製的元素缺陷率為 0.71。因此，請使用公式計算位置，並讓檢查器驗證結果。
在新機器上的前置檢查
安裝此技能不會安裝 MCP 伺服器——mcp-deps 是 vskill check 會驗證的宣告，而非安裝程式。如果 mcp__excalidraw__* 工具不可用，請先執行以下指令——它會檢測並註冊伺服器，適用於任何作業系統：
python3 scripts/ensure_mcp.py --install
它會回報伺服器的位置，或執行 claude mcp add --transport http --scope user excalidraw https://mcp.excalidraw.com 並重新驗證。結束碼 0 表示已設定完成，1 表示找不到，2 表示無法註冊（PATH 中沒有 Claude CLI——它會印出需要手動執行的指令）。Claude Code 在新增伺服器後需要重新啟動才能載入。
範圍：--scope user（預設）會涵蓋機器上所有專案，透過 ~/.claude.json；--scope project 會寫入 ./.mcp.json，讓團隊成員在 clone 後即可使用；--scope local 僅限此專案。在某個不同專案下註冊的伺服器會被視為缺失——Claude Code 不會在此載入它，腳本也會明確告知。
如果沒有 MCP，除了即時內嵌渲染外的所有功能仍然正常運作。 excalidraw_build.py 和 excalidraw_lint.py 僅需 Python 3 標準函式庫——不需要套件，也不需要網路。建構檔案、檢查、傳送。excalidraw_render.py 還需要 pip install playwright && playwright install chromium。
Windows
請使用 py -3 和反斜線，Windows 上的 python3 是 Microsoft Store 的樁程式，會開啟商店而不是執行任何內容。
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
其他部分都是可移植的：路徑透過 pathlib 處理，輸出使用明確的 UTF-8 和 \n 換行，這樣 Windows 執行時就不會將 CRLF 寫入場景 JSON，且前置檢查會解析 claude.cmd / claude.exe 以及 claude。如果 vskill i 警告說符號連結不可用，它會改為複製——啟用開發者模式即可恢復符號連結。
工作流程
- 前置檢查（僅限新機器）：如果
mcp__excalidraw__*工具缺失，請執行python3 scripts/ensure_mcp.py --install（Windows 上使用py -3）。 - 撰寫骨架。 一個 JSON 陣列，與
create_view接受的格式相同。位置來自佈局公式（請參閱references/layout-recipes.md），絕不靠目測。 - 檢查它——離線、無依賴、捕捉溢位／碰撞／幾何問題：
python3 scripts/excalidraw_lint.py scene.json --camera--camera會印出一個正確取景的 4:3cameraUpdate，以便貼在頂端。 - 即時渲染使用
mcp__excalidraw__create_view，元素依 Z 順序串流顯示並配合鏡頭移動（請參閱references/mcp-workflow.md）。保留回傳的checkpointId。 - 儲存檔案當使用者想要磁碟上的檔案時：
python3 scripts/excalidraw_build.py scene.json -o out.excalidraw python3 scripts/excalidraw_build.py scene.json -o out --obsidian # → out.excalidraw.md python3 scripts/excalidraw_build.py scene.json -o out.excalidraw --dark - 查看它在宣告任何非簡單圖表成功之前。此步驟透過 Excalidraw 自己的
exportToSvg渲染，因此文字會使用真實字型度量進行測量：
然後讀取 PNG。修正你所看到的；重新檢查；重新渲染。python3 scripts/excalidraw_render.py out.excalidraw -o /tmp/preview.png
步驟 2 和 5 是品質把關。跳過它們就是標籤跑到方塊外面、箭頭指著空無一物的原因。
骨架速查表
{"type":"rectangle","id":"api","x":100,"y":80,"width":180,"height":80,
"roundness":{"type":3},"backgroundColor":"#a5d8ff","fillStyle":"solid",
"strokeColor":"#4a9eed","label":{"text":"API Gateway","fontSize":18}}
{"type":"arrow","id":"e1","from":"api","to":"db","label":{"text":"SQL"}} // 自動綁定
{"type":"arrow","id":"e2","from":"api","to":"db","route":"ortho"} // L 形
{"type":"arrow","id":"e3","x":300,"y":150,"points":[[0,0],[120,0]]} // 手動
{"type":"text","id":"ttl","center":400,"y":20,"text":"Title","fontSize":24} // 自動置中
{"type":"rectangle","id":"zone","x":40,"y":40,"width":700,"height":420,
"opacity":30,"zoneLabel":"Data layer"} // 標題，非綁定標籤
建構器專用擴充：from／to（周邊錨點 + 雙向綁定）、route:"ortho"、zoneLabel、文字上的 center、形狀上的 fixedWidth（換行而非延伸）。其他所有內容原封不動傳遞，因此同一個陣列仍然可以直接與 create_view 搭配使用。
絕對不要將綁定的 label 放在背景區域矩形上——它會置中在區域中間且無法選取。請使用 zoneLabel。
選擇輸出
| 目的地 | 指令 | 備註 |
|---|---|---|
| 立即展示給使用者 | create_view | 動畫、鏡頭導引；回傳 checkpointId |
| 存放在儲存庫中的檔案 | excalidraw_build.py -o x.excalidraw | 可在 excalidraw.com 或 VS Code 擴充功能中開啟 |
| Obsidian 筆記庫 | ... -o x --obsidian | .excalidraw.md，可由外掛解析，支援 git diff |
| 可分享的連結 | mcp__excalidraw__export_to_excalidraw | 上傳至 excalidraw.com——請先詢問使用者 |
MCP 沒有本機檔案工具。export_to_excalidraw 是公開上傳，因此請視為發布：在呼叫前與使用者確認。
迭代
create_view 會回傳一個 checkpointId。若要從該處繼續——包括使用者在全螢幕中所做的編輯——請在下一個陣列開頭加入 {"type":"restoreCheckpoint","id":"<checkpointId>"}，並僅附加新的內容。使用 {"type":"delete","ids":"a,b"} 來移除元素；切勿重複使用已刪除的 id。請保持磁碟上的骨架檔案同步，因為該檔案是建構和檢查的來源。
參考資料
references/file-format.md——磁碟結構，已與上游驗證：字型代碼、綁定文字、箭頭幾何、綁定關係、Excalidraw 在開啟時會與不會重新計算的內容。在手工編輯任何.excalidraw檔案前請先閱讀。references/mcp-workflow.md——鏡頭編排、串流順序、檢查點、深色模式以及 MCP 本身的限制。references/layout-recipes.md——流程圖、分層圖、泳道圖、序列圖、網格圖、放射圖和矩陣圖的佈局公式，以及如何讓 60 個元素的圖表保持清晰可讀。references/obsidian.md——.excalidraw.md包裝器、區塊引用規則以及壓縮場景的問題。scripts/ensure_mcp.py——在任何作業系統上檢測並註冊 Excalidraw MCP 伺服器。scripts/split_excalidraw_library.py——將.excalidrawlib（來自 libraries.excalidraw.com 的 AWS／GCP／K8s 圖示包）拆分為每個圖示的 JSON 檔案和查詢表，使圖示資料絕不進入上下文。
值得說明的限制
- 寬度估計是逐字元校準的，而非從字型檔案測量得出；檢查器會在溢位 10% 以內發出警告。當它對重要內容發出警告時，請進行渲染。
excalidraw_render.py需要playwright以及對 esm.sh 的網路存取。沒有這些，檢查仍然可以完全離線進行。- 檢查器無法判斷圖表是否好，只能判斷它是否正確。構圖仍然是你的工作。
更新日誌
- 1.2.0——
scripts/ensure_mcp.py：跨平台前置檢查，可檢測 MCP 伺服器（包括~/.claude.json的按專案地圖）並在缺失時註冊。Windows 支援：記錄py -3、claude.cmd解析、每次寫入時使用明確的 UTF-8 和\n換行。 - 1.1.1——檢查器不再對箭頭容器套用方塊貼合規則（R1／R2）；箭頭標籤沿路徑佈局，並由 R10 涵蓋。
- 1.1.0——移至
skills/excalidraw-mcp/目錄下的 vskill 單一儲存庫，與remotion-best-practices及其他儲存庫內的技能保持一致。獨立的anton-abyzov/excalidraw-mcp-skill儲存庫已棄用。 - 1.0.1——記錄 MCP 設定：安裝技能並不會安裝伺服器；新增
claude mcp add一行指令以及哪些功能在沒有它的情況下仍然正常運作。 - 1.0.0——首次發布。取代僅限檔案的
excalidraw-diagram-generator技能，其範本在形狀上內嵌了text，因此開啟時會顯示為空白方塊。