Excalidraw via MCP
Die Aussage „Verwende Excalidraw MCP“ sollte ausreichen, um ein komplexes Diagramm live zu zeichnen und dort zu speichern, wo es hingehört. Diese Fähigkeit macht das möglich.
Die eine Sache, die alles kaputt macht
Das Elementformat von create_view ist ein Skelett, nicht das On-Disk-Schema. Ein Label einer
Form ist nur Skelett-Zucker. Der Canvas-Renderer von Excalidraw hat keinen Textzweig für
Rechteck / Ellipse / Raute – Containerext wird nur über
boundElements → containerId gezeichnet. Das Einfügen von create_view-JSON in eine .excalidraw-Datei
führt daher zu leeren Boxen, stillschweigend. Dieser eine Fakt ist der Grund, warum
scripts/excalidraw_build.py existiert: Einmal im Skelett erstellen, erhalten Sie sowohl die Live-Darstellung als auch eine korrekte Datei.
Zweite Tatsache: Handgezeichnete Diagramme degradieren nicht allmählich mit der Größe – sie scheitern an Unregelmäßigkeit. Gemessen an einer echten generierten Szene hatten Elemente, die von einer wiederholten Layoutformel erzeugt wurden, eine Fehlerrate von 0,00; maßgeschneiderte Einzelelemente hatten 0,71. Berechnen Sie also Positionen mit einer Formel und lassen Sie den Linter das Ergebnis prüfen.
Vorbereitung auf einem neuen Rechner
Die Installation dieser Fähigkeit installiert nicht den MCP-Server – mcp-deps ist eine Deklaration,
die vskill check überprüft, kein Installer. Wenn die mcp__excalidraw__*-Werkzeuge nicht
verfügbar sind, führen Sie zuerst dies aus – es erkennt und registriert den Server auf jedem Betriebssystem:
python3 scripts/ensure_mcp.py --install
Es meldet, wo der Server gefunden wurde, oder führt
claude mcp add --transport http --scope user excalidraw https://mcp.excalidraw.com
aus und überprüft erneut. Exit-Code 0: konfiguriert, 1: fehlt, 2: Registrierung nicht möglich (kein Claude CLI im
Pfad – es gibt den auszuführenden Befehl aus). Claude Code muss danach neu gestartet werden, um einen neu
hinzugefügten Server zu erkennen.
Bereiche: --scope user (Standard) deckt jedes Projekt auf dem Rechner über ~/.claude.json ab;
--scope project schreibt ./.mcp.json, sodass Teammitglieder es beim Klonen erhalten; --scope local ist
nur dieses Projekt. Ein Server, der unter einem anderen Projekt registriert ist, gilt als fehlend –
Claude Code wird ihn hier nicht laden, und das Skript sagt das.
Ohne das MCP funktioniert alles außer der Live-Inline-Darstellung weiterhin.
excalidraw_build.py und excalidraw_lint.py sind reine Python-3-Module – keine Pakete, kein
Netzwerk. Dateien erstellen, linten, verteilen. excalidraw_render.py benötigt zusätzlich
pip install playwright && playwright install chromium.
Windows
Verwenden Sie py -3 und Backslashes; python3 unter Windows ist ein Microsoft-Store-Stub, der den Store
öffnet, anstatt etwas auszuführen.
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
Alles andere ist portabel: Pfade gehen durch pathlib, die Ausgabe erfolgt mit explizitem UTF-8
und \n-Zeilenumbrüchen, sodass ein Windows-Durchlauf keine CRLF in das Szenen-JSON einbrennt, und die
Vorbereitung löst claude.cmd / claude.exe sowie claude auf. Wenn vskill i warnt,
dass Symlinks nicht verfügbar sind, wird auf Kopieren zurückgegriffen – aktivieren Sie den Entwicklermodus, um
Symlinks wieder zu erhalten.
Arbeitsablauf
- Vorbereitung (nur neuer Rechner): Falls die
mcp__excalidraw__*-Werkzeuge fehlen,python3 scripts/ensure_mcp.py --install(py -3unter Windows). - Skelett erstellen. Ein JSON-Array, das gleiche, das
create_viewerwartet. Positionen stammen aus einer Layoutformel (siehereferences/layout-recipes.md), niemals durch Augenmaß. - Linten – offline, keine Abhängigkeiten, erkennt Überlauf/Kollision/Geometrie:
python3 scripts/excalidraw_lint.py scene.json --camera--cameragibt ein korrekt gerahmtes 4:3cameraUpdateaus, das oben eingefügt werden kann. - Live darstellen mit
mcp__excalidraw__create_view, Elemente in Z-Reihenfolge mit Kamerabewegungen streamen (siehereferences/mcp-workflow.md). Behalten Sie die zurückgegebenecheckpointId. - Datei speichern, wenn der Benutzer eine auf der Festplatte möchte:
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 - Anschauen, bevor Sie bei etwas Nicht-Trivialem den Erfolg erklären. Dies rendert mit
Excalidraws eigenem
exportToSvg, sodass Text mit echten Schriftmetriken gemessen wird:
Dann das PNG lesen. Korrigieren, was Sie sehen; erneut linten; erneut rendern.python3 scripts/excalidraw_render.py out.excalidraw -o /tmp/preview.png
Die Schritte 2 und 5 sind das Qualitätstor. Wenn Sie sie überspringen, landen Labels außerhalb ihrer Boxen und Pfeile zeigen ins Leere.
Skelett-Spickzettel
{"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"}} // automatisch gebunden
{"type":"arrow","id":"e2","from":"api","to":"db","route":"ortho"} // L-förmig
{"type":"arrow","id":"e3","x":300,"y":150,"points":[[0,0],[120,0]]} // manuell
{"type":"text","id":"ttl","center":400,"y":20,"text":"Titel","fontSize":24} // automatisch zentriert
{"type":"rectangle","id":"zone","x":40,"y":40,"width":700,"height":420,
"opacity":30,"zoneLabel":"Datenschicht"} // Beschriftung, kein gebundenes Label
Builder-spezifische Erweiterungen: from/to (Umfangsanker + bidirektionale Bindung),
route:"ortho", zoneLabel, center bei Text, fixedWidth bei einer Form (umbricht statt
wächst). Alles andere wird unverändert durchgereicht, sodass das gleiche Array auch direkt mit
create_view funktioniert.
Setzen Sie niemals ein gebundenes label auf ein Hintergrundzonen-Rechteck – es zentriert sich in der Mitte
der Zone und kann nicht gegriffen werden. Verwenden Sie zoneLabel.
Ausgabe wählen
| Ziel | Befehl | Hinweise |
|---|---|---|
| Benutzer jetzt anzeigen | create_view | animiert, kamerageführt; gibt checkpointId zurück |
| Datei in einem Repository | excalidraw_build.py -o x.excalidraw | öffnet bei excalidraw.com oder in der VS Code-Erweiterung |
| Obsidian-Vault | ... -o x --obsidian | .excalidraw.md, plugin-parsbares, git-diffbares Format |
| Teilbarer Link | mcp__excalidraw__export_to_excalidraw | lädt zu excalidraw.com hoch – vorher fragen |
Das MCP hat kein lokales Dateiwerkzeug. export_to_excalidraw ist ein öffentlicher Upload, also behandeln Sie ihn
als Veröffentlichung: Bestätigen Sie mit dem Benutzer, bevor Sie es aufrufen.
Iterieren
create_view gibt eine checkpointId zurück. Um daran anzuknüpfen – einschließlich vom Benutzer im Vollbildmodus
vorgenommener Änderungen – beginnen Sie das nächste Array mit
{"type":"restoreCheckpoint","id":"<checkpointId>"} und hängen Sie nur Neue an. Verwenden Sie
{"type":"delete","ids":"a,b"}, um Elemente zu entfernen; verwenden Sie eine gelöschte ID nie wieder. Halten Sie die
Skelettdatei auf der Festplatte synchron, da diese Datei zum Erstellen und Linten verwendet wird.
Referenzen
references/file-format.md– das On-Disk-Schema, überprüft gegen den Upstream: Schrift- codes, gebundener Text, Pfeilgeometrie, Bindungen, was Excalidraw beim Öffnen neu berechnet und was nicht. Lesen Sie dies, bevor Sie eine.excalidraw-Datei von Hand bearbeiten.references/mcp-workflow.md– Kamerachoreografie, Streaming-Reihenfolge, Checkpoints, Dunkelmodus und die eigenen Grenzen des MCP.references/layout-recipes.md– Formeln für Fluss-, Ebenen-, Swimlane-, Sequenz-, Raster-, Radial- und Matrixlayouts sowie wie man ein 60-Elemente-Diagramm lesbar hält.references/obsidian.md– der.excalidraw.md-Wrapper, Block-Ref-Regeln und die Komprimierte-Szene-Falle.scripts/ensure_mcp.py– Erkennt und registriert den Excalidraw-MCP-Server auf jedem Betriebssystem.scripts/split_excalidraw_library.py– Teilt eine.excalidrawlib(AWS/GCP/K8s-Icon-Pakete von libraries.excalidraw.com) in JSON pro Icon plus eine Nachschlagetabelle auf, sodass Icon-Daten nie in den Kontext gelangen.
Grenzen, die man laut aussprechen sollte
- Breitenschätzungen werden pro Zeichen kalibriert, nicht aus der Schriftart-Binärdatei gemessen; der Linter warnt innerhalb von 10% vor Überlauf. Wenn er bei etwas Wichtigem warnt, rendern Sie es.
excalidraw_render.pybenötigtplaywrightplus Netzwerkzugriff auf esm.sh. Ohne diese ist der Lint immer noch vollständig offline.- Der Linter kann nicht beurteilen, ob ein Diagramm gut ist, sondern nur, ob es korrekt ist. Die Komposition ist immer noch Ihre Aufgabe.
Änderungsprotokoll
- 1.2.0 –
scripts/ensure_mcp.py: Plattformübergreifende Vorbereitung, die den MCP-Server erkennt (einschließlich der projektspezifischen Zuordnung in~/.claude.json) und registriert, wenn er fehlt. Windows-Unterstützung: dokumentiertpy -3,claude.cmd-Auflösung, explizites UTF-8 und\n- Zeilenumbrüche bei jedem Schreibvorgang. - 1.1.1 – Linter wendet die Box-Fit-Regeln (R1/R2) nicht mehr auf Pfeilcontainer an; Pfeillabels werden entlang des Pfades angeordnet und fallen unter R10.
- 1.1.0 – In das vskill-Monorepo unter
skills/excalidraw-mcp/verschoben, passend zuremotion-best-practicesund den anderen im Repo enthaltenen Fähigkeiten. Das eigenständigeanton-abyzov/excalidraw-mcp-skill-Repository ist veraltet. - 1.0.1 – MCP-Setup dokumentiert: Die Installation der Fähigkeit installiert nicht den Server;
der
claude mcp add-Einzeiler und was noch ohne ihn funktioniert, hinzugefügt. - 1.0.0 – Erste Veröffentlichung. Ersetzt die dateibasierte Fähigkeit
excalidraw-diagram-generator, deren Vorlagen Inline-textauf Formen ausgaben und daher als leere Boxen geöffnet wurden.