Excalidraw via 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__* 도구를 사용할 수 없는 경우, 먼저 이 명령을 실행하세요. 모든 OS에서 서버를 감지하고 등록합니다:
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을 작성하여 팀원이 클론할 때 사용할 수 있게 합니다. --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 스텁으로, 실제로 실행하는 대신 Store를 엽니다.
py -3 scripts\ensure_mcp.py --install
py -3 scripts\excalidraw_build.py scene.json -o out.excalidraw
다른 모든 것은 이식 가능합니다. 경로는 pathlib를 거치고, 출력은 명시적 UTF-8과 \n 개행 문자로 작성되어 Windows 실행이 장면 JSON에 CRLF를 주입하지 않도록 합니다. 사전 점검은 claude.cmd / claude.exe뿐만 아니라 claude도 확인합니다. vskill i가 심볼릭 링크를 사용할 수 없다고 경고하면 복사로 대체합니다. 개발자 모드를 활성화하여 심볼릭 링크를 다시 사용하세요.
워크플로
- 사전 점검 (새 컴퓨터에서만):
mcp__excalidraw__*도구가 없으면python3 scripts/ensure_mcp.py --install(Windows에서는 py -3)을 실행합니다. - 스켈레톤 작성.
create_view가 받는 것과 동일한 JSON 배열 하나입니다. 위치는 레이아웃 공식(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— 모든 OS에서 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 —
vskill모노레포의skills/excalidraw-mcp/로 이동,remotion-best-practices및 기타 저장소 내 스킬과 일치. 독립형anton-abyzov/excalidraw-mcp-skill저장소는 더 이상 사용되지 않음. - 1.0.1 — MCP 설정 문서화: 스킬 설치가 서버를 설치하지 않음.
claude mcp add한 줄 명령어와 서버 없이도 작동하는 기능 추가. - 1.0.0 — 첫 번째 릴리스. 파일 전용
excalidraw-diagram-generator스킬을 대체. 해당 스킬의 템플릿은 도형에 인라인text를 방출하여 빈 상자로 열렸음.