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 CLI 등)가 구동할 수 있게 합니다. 에이전트는 다음을 수행할 수 있습니다:
- JSON 명령을 통해 개별 다이어그램 요소를 생성, 읽기, 업데이트, 삭제합니다.
- 라이브 캔버스의 스크린샷을 캡처합니다(이제 Node에서 헤드리스로 렌더링되며 브라우저가 필요 없습니다).
- 다이어그램을 반복적으로 개선합니다: 그리기 → 설명 → 스크린샷 → 조정 → 반복.
- 결과를 기본
.excalidraw파일(또는 Obsidian 호환.excalidraw.md)로 내보내기하여 코드와 함께 버전 관리할 수 있습니다. - Mermaid 다이어그램을 가져오기 및 병합하고, 암호화된 URL을 공유하며, 명명된 스냅샷을 찍습니다.
이 모든 것은 세 가지 상호 교환 가능한 인터페이스를 통해 제공됩니다:
- CLI(
npx -y mcp-excalidraw-server <command>) – 에이전트에게 권장되는 방법. - MCP 서버 – 모든 MCP 호환 클라이언트를 위해 Model Context Protocol(MCP 2026‑07‑28)을 사용합니다.
- REST API – LangChain 또는 사용자 지정 HTTP 호출자용.
실제 그리기는 로컬 Node ≥ 20 프로세스에서 발생하며 외부 API 키가 필요하지 않습니다.
사용 대상
- 개발 워크플로의 일부로 아키텍처 다이어그램, 순서도 또는 UI 목업을 생성해야 하는 코딩 어시스턴트.
- 소스 코드가 변경될 때 업데이트된 다이어그램을 자동으로 렌더링하는 CI 파이프라인.
- 시각적 자산을 코드와 동기화 상태로 유지하는 문서 파이프라인(예: Obsidian 볼트).
- 여러 에이전트가 동시에 편집할 수 있는 공유 실시간 캔버스를 원하는 팀.
시작 방법
# 한 줄: 캔버스를 시작하고 감시합니다(선택 사항)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 브라우저에서 UI 보기
# JSON으로 두 개의 상자와 화살표 그리기
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"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"}
]
EOF
# 에이전트가 다이어그램을 보고 PNG를 캡처하도록 허용
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 다이어그램을 저장소 아티팩트로 저장
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
동일한 명령은 Docker 컨테이너 내부 또는 npm ci 후 소스에서도 작동합니다.
주요 기능 한눈에 보기
| 기능 | 제공 내용 |
|---|---|
| CLI 우선 설계 | 모든 캔버스 작업은 구성 가능한 JSON 명령이며, 종료 코드로 스크립팅이 쉽습니다. |
| MCP 호환성 | 최신 MCP 프로토콜을 사용하여 Claude Desktop, Cursor, Codex CLI, Antigravity 등과 작동합니다(핸드셰이크 불필요). |
| 헤드리스 렌더링 | 스크린샷 및 이미지 내보내기는 jsdom + resvg를 통해 Node 내부에서 생성됩니다 – 빠르고 결정적이며 CI 친화적입니다. |
| 결정적 내보내기 | 변경되지 않은 장면에 대해 바이트 동일한 .excalidraw 파일 → 잡음이 많은 git diff 없음. |
| Obsidian 지원 | 블록 참조를 보존하면서 Obsidian Excalidraw 플러그인용 .excalidraw.md로 내보냅니다. |
| Mermaid 가져오기 | Mermaid 텍스트를 라이브 Excalidraw 요소로 변환하고 기존 콘텐츠와 병합합니다. |
| 스냅샷 시스템 | 명명된 저장/복원 지점을 통해 에이전트가 다이어그램 상태를 롤백하거나 분기할 수 있습니다. |
| 레이아웃 도구 | 정렬, 분배, 그룹/그룹 해제, 잠금, 복제 – 모두 MCP 도구 또는 CLI 플래그를 통해. |
| 공유 가능한 URL | 쉬운 공유를 위한 선택적 암호화 업로드 to excalidraw.com. |
| 제로 구성 시작 | 첫 번째 그리기 명령이 캔버스 서버를 자동으로 시작합니다. EXCALIDRAW_NO_AUTOSTART=1로 비활성화할 수 있습니다. |
제한 사항 / 주의 사항
- 서버는 기본적으로
127.0.0.1에만 바인딩됩니다. 외부에 노출하려면 자체 네트워크 방화벽이 필요합니다 – API에는 내장 인증이 없습니다. - 일부 명령(
mermaid변환,--renderer browser스크린샷)은 여전히 실제 브라우저 탭이 열려 있어야 합니다. - Node ≥ 20이 필요합니다. 이전 버전은 지원되지 않습니다.
- 글꼴 범위는 번들된 TTF로 제한되며, 특수 스크립트는 호스트 OS 글꼴로 대체됩니다.
라이선스 및 커뮤니티
- MIT 라이선스 – 상업적 및 개인적 사용에 무료입니다.
- npm에
mcp-excalidraw-server로 게시됨(배지가 현재 버전을 표시). - CI 배지는 자동화된 테스트 및 Docker 빌드를 나타냅니다.
- 기여를 환영합니다. 저장소에는
CONTRIBUTING스타일 가이드와 소스에서 빌드하기 위한development섹션이 포함되어 있습니다.
TL;DR
mcp-excalidraw-server는 로컬에서 실행되는 CLI 기반 Excalidraw 캔버스로, AI 코딩 에이전트가 변경 가능한 그리기 표면으로 취급할 수 있습니다. 요소 수준의 CRUD, 헤드리스 스크린샷, 결정적 내보내기, 전체 MCP/REST 통합을 제공하여 AI 워크플로에서 직접 다이어그램을 생성, 개선, 버전 관리하기 쉽게 만듭니다.
시작 방법
# 한 줄: 캔버스를 시작하고 감시합니다(선택 사항)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 브라우저에서 UI 보기
# JSON으로 두 개의 상자와 화살표 그리기
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"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"}
]
EOF
# 에이전트가 다이어그램을 보고 PNG를 캡처하도록 합니다
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 다이어그램을 저장소 아티팩트로 저장
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
동일한 명령은 Docker 컨테이너 내부 또는 npm ci 후 소스에서도 작동합니다.
주요 기능 한눈에 보기
| 기능 | 제공 내용 |
|---|---|
| CLI 우선 설계 | 모든 캔버스 작업은 구성 가능한 JSON 명령이며, 종료 코드로 스크립팅이 쉽습니다. |
| MCP 호환성 | 최신 MCP 프로토콜(핸드셰이크 불필요)을 사용하여 Claude Desktop, Cursor, Codex CLI, Antigravity 등과 작동합니다. |
| 헤드리스 렌더링 | 스크린샷 및 이미지 내보내기는 jsdom + resvg를 통해 Node 내부에서 생성됩니다 – 빠르고, 결정적이며, CI 친화적입니다. |
| 결정적 내보내기 | 변경되지 않은 장면에 대해 바이트 동일한 .excalidraw 파일 → 시끄러운 git diff 없음. |
| Obsidian 지원 | 블록 참조를 보존하면서 Obsidian Excalidraw 플러그인용 .excalidraw.md로 내보냅니다. |
| Mermaid 가져오기 | Mermaid 텍스트를 라이브 Excalidraw 요소로 변환하고 기존 콘텐츠와 병합합니다. |
| 스냅샷 시스템 | 명명된 저장/복원 지점을 통해 에이전트가 다이어그램 상태를 롤백하거나 분기할 수 있습니다. |
| 레이아웃 도구 | 정렬, 분산, 그룹/그룹 해제, 잠금, 복제 – 모두 MCP 도구 또는 CLI 플래그를 통해 사용 가능합니다. |
| 공유 가능한 URL | 쉬운 공유를 위해 excalidraw.com에 선택적 암호화 업로드. |
| 제로 구성 시작 | 첫 번째 그리기 명령이 캔버스 서버를 자동으로 시작합니다. EXCALIDRAW_NO_AUTOSTART=1로 비활성화할 수 있습니다. |
제한 사항 / 주의 사항
- 서버는 기본적으로
127.0.0.1에만 바인딩됩니다. 외부에 노출하려면 자체 네트워크 방화벽이 필요합니다 – API에는 내장 인증이 없습니다. - 일부 명령(
mermaid변환,--renderer browser스크린샷)은 여전히 실제 브라우저 탭이 열려 있어야 합니다. - Node ≥ 20이 필요합니다. 이전 버전은 지원되지 않습니다.
- 글꼴 범위는 번들된 TTF로 제한되며, 특수 스크립트는 호스트 OS 글꼴로 대체됩니다.
라이선스 및 커뮤니티
- MIT 라이선스 – 상업적 및 개인적 사용에 무료입니다.
- npm에
mcp-excalidraw-server로 게시됨(배지가 현재 버전을 표시). - CI 배지는 자동화된 테스트와 Docker 빌드를 나타냅니다.
- 기여를 환영합니다. 저장소에는
CONTRIBUTING스타일 가이드와 소스에서 빌드하기 위한development섹션이 포함되어 있습니다.
TL;DR
mcp-excalidraw-server는 로컬에서 실행되는 CLI 기반 Excalidraw 캔버스로, AI 코딩 에이전트가 변경 가능한 그리기 표면으로 취급할 수 있습니다. 요소 수준의 CRUD, 헤드리스 스크린샷, 결정적 내보내기, 전체 MCP/REST 통합을 제공하여 AI 워크플로에서 직접 다이어그램을 생성, 개선, 버전 관리하기 쉽게 만듭니다.
시작 방법
# 한 줄: 캔버스를 시작하고 (선택 사항) 확인
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 브라우저에서 UI 보기
# JSON으로 두 개의 상자와 화살표 그리기
cat <<EOF | npx -y mcp-excalidraw-server add
[
{"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"}
]
EOF
# 에이전트가 다이어그램을 보고 PNG를 캡처하도록 함
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 다이어그램을 저장소 아티팩트로 저장
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw
동일한 명령은 Docker 컨테이너 내부 또는 npm ci 후 소스에서도 작동합니다.
주요 기능 한눈에 보기
| 기능 | 제공 내용 |
|---|---|
| CLI 우선 설계 | 모든 캔버스 작업은 구성 가능한 JSON 명령이며, 종료 코드로 스크립팅이 쉽습니다. |
| MCP 호환성 | 최신 MCP 프로토콜(핸드셰이크 불필요)을 사용하여 Claude Desktop, Cursor, Codex CLI, Antigravity 등과 작동합니다. |
| 헤드리스 렌더링 | 스크린샷 및 이미지 내보내기는 jsdom + resvg를 통해 Node 내부에서 생성됩니다 – 빠르고, 결정적이며, CI 친화적입니다. |
| 결정적 내보내기 | 변경되지 않은 장면에 대해 바이트 동일 .excalidraw 파일 → 지저분한 git diff 없음. |
| Obsidian 지원 | 블록 참조를 보존하면서 Obsidian Excalidraw 플러그인용 .excalidraw.md로 내보냅니다. |
| Mermaid 가져오기 | Mermaid 텍스트를 라이브 Excalidraw 요소로 변환하고 기존 콘텐츠와 병합합니다. |
| 스냅샷 시스템 | 명명된 저장/복원 지점을 통해 에이전트가 다이어그램 상태를 롤백하거나 분기할 수 있습니다. |
| 레이아웃 도구 | 정렬, 분산, 그룹/그룹 해제, 잠금, 복제 – 모두 MCP 도구 또는 CLI 플래그를 통해 사용 가능합니다. |
| 공유 가능한 URL | 쉬운 공유를 위해 excalidraw.com에 선택적 암호화 업로드. |
| 제로 구성 시작 | 첫 번째 그리기 명령이 캔버스 서버를 자동으로 시작합니다. EXCALIDRAW_NO_AUTOSTART=1로 비활성화할 수 있습니다. |
제한 사항 / 주의 사항
- 서버는 기본적으로
127.0.0.1에만 바인딩됩니다. 외부에 노출하려면 자체 네트워크 방화벽이 필요합니다 – API에는 내장 인증이 없습니다. - 일부 명령(
mermaid변환,--renderer browser스크린샷)은 여전히 실제 브라우저 탭이 열려 있어야 합니다. - Node ≥ 20이 필요합니다. 이전 버전은 지원되지 않습니다.
- 글꼴 범위는 번들된 TTF로 제한됩니다. 특수 스크립트는 호스트 OS 글꼴로 대체됩니다.
라이선스 및 커뮤니티
- MIT 라이선스 – 상업적 및 개인적 사용에 무료입니다.
- npm에
mcp-excalidraw-server로 게시됨(배지가 현재 버전을 표시). - CI 배지는 자동화된 테스트와 Docker 빌드를 나타냅니다.
- 기여를 환영합니다. 저장소에는
CONTRIBUTING스타일 가이드와 소스에서 빌드하기 위한development섹션이 포함되어 있습니다.
TL;DR
mcp-excalidraw-server는 로컬에서 실행되는 CLI 기반 Excalidraw 캔버스로, AI 코딩 에이전트가 변경 가능한 그리기 표면으로 취급할 수 있습니다. 요소 수준의 CRUD, 헤드리스 스크린샷, 결정적 내보내기, 전체 MCP/REST 통합을 제공하여 AI 워크플로에서 직접 다이어그램을 생성, 개선, 버전 관리하기 쉽게 만듭니다.
관련
- Dispatch
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트