Excalidraw via MCP
Dire « utilise Excalidraw MCP » devrait suffire pour obtenir un diagramme complexe, dessiné en direct et sauvegardé là où il faut. C'est ce que cette compétence rend possible.
La seule chose qui casse tout
Le format d'élément de create_view est un squelette, pas le schéma disque. Le
label d'une forme est un sucre syntaxique propre au squelette. Le moteur de rendu du canevas d'Excalidraw n'a pas de branche texte pour les rectangles / ellipses / losanges — le texte des conteneurs est dessiné uniquement via
boundElements → containerId. Donc coller du JSON create_view dans un fichier .excalidraw
produit des boîtes vides, silencieusement. C'est ce fait unique qui explique pourquoi
scripts/excalidraw_build.py existe : on écrit une fois dans le squelette, on obtient à la fois le rendu live et un fichier correct.
Deuxième fait : les diagrammes rédigés à la main ne se dégradent pas graduellement avec la taille — ils échouent à cause de l'irrégularité. Mesurée sur une scène générée réelle, les éléments produits par une formule de disposition répétitive avaient un taux de défaut de 0,00 ; les éléments uniques faits sur mesure avaient 0,71. Donc calculez les positions avec une formule, et laissez le linter vérifier le résultat.
Prérèglement sur une nouvelle machine
Installer cette compétence n'installe pas le serveur MCP — mcp-deps est une déclaration
que vskill check vérifie, pas un installateur. Si les outils mcp__excalidraw__* ne sont pas
disponibles, exécutez d'abord ceci — il détecte et enregistre le serveur, sur n'importe quel OS :
python3 scripts/ensure_mcp.py --install
Il signale où le serveur a été trouvé, ou exécute
claude mcp add --transport http --scope user excalidraw https://mcp.excalidraw.com
et revérifie. Code de sortie 0 configuré, 1 manquant, 2 impossible d'enregistrer (pas de CLI Claude dans le
PATH — il affiche la commande à exécuter manuellement). Claude Code a besoin d'un redémarrage après pour
prendre en compte un serveur nouvellement ajouté.
Étendues : --scope user (par défaut) couvre tous les projets de la machine via ~/.claude.json ;
--scope project écrit ./.mcp.json pour que les coéquipiers l'obtiennent au clonage ; --scope local est
ce projet uniquement. Un serveur enregistré sous un projet différent est considéré comme manquant —
Claude Code ne le chargera pas ici, et le script le signale.
Sans le MCP, tout sauf le rendu inline en direct fonctionne encore.
excalidraw_build.py et excalidraw_lint.py sont du Python 3 sans dépendances autres que la bibliothèque standard — pas de paquets, pas de
réseau. Construisez les fichiers, lintez-les, expédiez-les. excalidraw_render.py nécessite en plus
pip install playwright && playwright install chromium.
Windows
Utilisez py -3 et des antislashs ; python3 sur Windows est un stub Microsoft Store qui ouvre le Store
au lieu d'exécuter quoi que ce soit.
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
Tout le reste est portable : les chemins passent par pathlib, la sortie est écrite avec un UTF-8 explicite
et des sauts de ligne \n pour qu'une exécution Windows n'intègre pas CRLF dans le JSON de la scène, et le
prérèglement résout claude.cmd / claude.exe ainsi que claude. Si vskill i prévient
que les liens symboliques ne sont pas disponibles, il se rabat sur la copie — activez le mode développeur pour obtenir
à nouveau les liens symboliques.
Workflow
- Prérèglement (nouvelle machine uniquement) : si les outils
mcp__excalidraw__*sont absents,python3 scripts/ensure_mcp.py --install(py -3sur Windows). - Rédigez le squelette. Un tableau JSON, le même que celui accepté par
create_view. Les positions proviennent d'une formule de disposition (voirreferences/layout-recipes.md), jamais d'une estimation visuelle. - Lintez-le — hors ligne, sans dépendances, détecte les débordements/collisions/problèmes géométriques :
python3 scripts/excalidraw_lint.py scene.json --camera--cameraaffiche uncameraUpdatecorrectement cadré au format 4:3 à coller en haut. - Rendez-le en direct avec
mcp__excalidraw__create_view, les éléments diffusés dans l'ordre z avec les mouvements de caméra (voirreferences/mcp-workflow.md). Conservez lecheckpointIdretourné. - Sauvegardez le fichier lorsque l'utilisateur en veut un sur le disque :
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 - Regardez-le avant de déclarer le succès sur quoi que ce soit de non trivial. Ceci rend via
exportToSvgd'Excalidraw propre, donc le texte est mesuré avec les métriques de police réelles :
Lisez ensuite le PNG. Corrigez ce que vous voyez ; re-lintez ; re-rendez.python3 scripts/excalidraw_render.py out.excalidraw -o /tmp/preview.png
Les étapes 2 et 5 sont la porte qualité. Les sauter est la raison pour laquelle les étiquettes finissent hors de leurs boîtes et les flèches pointent vers rien.
Aide-mémoire du squelette
{"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"}} // liaison automatique
{"type":"arrow","id":"e2","from":"api","to":"db","route":"ortho"} // en L
{"type":"arrow","id":"e3","x":300,"y":150,"points":[[0,0],[120,0]]} // manuel
{"type":"text","id":"ttl","center":400,"y":20,"text":"Titre","fontSize":24} // centré automatiquement
{"type":"rectangle","id":"zone","x":40,"y":40,"width":700,"height":420,
"opacity":30,"zoneLabel":"Couche données"} // légende, pas d'étiquette liée
Extensions propres au constructeur : from/to (ancres de périmètre + liaison bidirectionnelle),
route:"ortho", zoneLabel, center sur le texte, fixedWidth sur une forme (retour à la ligne au lieu
s'étendre). Tout le reste est transmis inchangé, donc le même tableau fonctionne toujours
tel quel avec create_view.
Ne mettez jamais d'étiquette liée label sur un rectangle de zone d'arrière-plan — elle se centre au milieu
de la zone et ne peut pas être attrapée. Utilisez zoneLabel.
Choisir la sortie
| Destination | Commande | Notes |
|---|---|---|
| Montrer immédiatement à l'utilisateur | create_view | animé, guidé par caméra ; retourne checkpointId |
| Fichier dans un dépôt | excalidraw_build.py -o x.excalidraw | s'ouvre sur excalidraw.com ou dans l'extension VS Code |
| Coffre Obsidian | ... -o x --obsidian | .excalidraw.md, parsé par plugin, diffable via git |
| Lien partageable | mcp__excalidraw__export_to_excalidraw | importe vers excalidraw.com — demandez d'abord |
Le MCP n'a pas d'outil de fichier local. export_to_excalidraw est un import public, donc traitez-le
comme une publication : confirmez avec l'utilisateur avant de l'appeler.
Itérer
create_view retourne un checkpointId. Pour continuer à partir de celui-ci — y compris les modifications utilisateur faites en
plein écran — commencez le tableau suivant par
{"type":"restoreCheckpoint","id":"<checkpointId>"} et n'ajoutez que ce qui est nouveau. Utilisez
{"type":"delete","ids":"a,b"} pour supprimer des éléments ; ne réutilisez jamais un identifiant supprimé. Gardez le
fichier squelette sur le disque synchronisé, car c'est ce fichier qui construit et linte.
Références
references/file-format.md— le schéma disque, vérifié par rapport à la source amont : codes de police, texte lié, géométrie des flèches, liaisons, ce qu'Excalidraw recompute ou non à l'ouverture. À lire avant d'éditer manuellement tout fichier.excalidraw.references/mcp-workflow.md— chorégraphie de la caméra, ordre de diffusion, points de contrôle, mode sombre, et les propres limites du MCP.references/layout-recipes.md— formules pour les dispositions en flux, en couches, en couloir, en séquence, en grille, radiale et matricielle, ainsi que comment garder un diagramme à 60 éléments lisible.references/obsidian.md— le wrapper.excalidraw.md, les règles de bloc-ref, et le piège de la scène compressée.scripts/ensure_mcp.py— détecte et enregistre le serveur Excalidraw MCP sur n'importe quel OS.scripts/split_excalidraw_library.py— divise un.excalidrawlib(packs d'icônes AWS/GCP/K8s de libraries.excalidraw.com) en JSON par icône plus une table de correspondance, afin que les données d'icône n'entrent jamais dans le contexte.
Limites à énoncer clairement
- Les estimations de largeur sont calibrées par caractère, pas mesurées à partir du binaire de police ; le linter prévient à moins de 10 % du débordement. Quand il prévient sur quelque chose d'important, rendez-le.
excalidraw_render.pynécessiteplaywrightplus un accès réseau à esm.sh. Sans eux, le lint reste entièrement hors ligne.- Le linter ne peut pas juger si un diagramme est bon, seulement s'il est correct. La composition reste votre travail.
Journal des modifications
- 1.2.0 —
scripts/ensure_mcp.py: prérèglement multiplateforme qui détecte le serveur MCP (y compris la carte par projet de~/.claude.json) et l'enregistre quand il est manquant. Support Windows : documentépy -3, résolution declaude.cmd, UTF-8 explicite et sauts de ligne\nsur chaque écriture. - 1.1.1 — le linter n'applique plus les règles d'ajustement de boîte (R1/R2) aux conteneurs de flèches ; les étiquettes de flèches sont disposées le long du chemin et sont couvertes par R10.
- 1.1.0 — déplacé dans le monorepo vskill à
skills/excalidraw-mcp/, en correspondance avecremotion-best-practiceset les autres compétences du dépôt. Le dépôt autonomeanton-abyzov/excalidraw-mcp-skillest obsolète. - 1.0.1 — documentation de la configuration MCP : installer la compétence n'installe pas le serveur ;
ajout de la commande en une ligne
claude mcp addet de ce qui fonctionne encore sans. - 1.0.0 — première version. Remplace la compétence
excalidraw-diagram-generatorlimitée aux fichiers, dont les modèles émettaient dutextinline sur les formes et s'ouvraient donc comme des boîtes vides.