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 등)가 제어할 수 있는 프로그래밍 가능한 워크벤치로 바꿔줍니다. 캔버스는 완전히 로컬에서 실행되며(Node ≥ 20, API 키 불필요), 다음 세 가지 방법으로 액세스할 수 있습니다.
- CLI –
npx -y mcp-excalidraw-server <command>– 캔버스를 자동으로 시작하고, 요소 추가/업데이트/삭제, 스크린샷 캡처, 파일 내보내기 등을 수행하는 JSON 기반 명령 모음. - MCP 서버 – 26개의 도구를 노출하는 Model Context Protocol(MCP) stdio 서버. MCP 호환 클라이언트가 그리기 작업을 직접 호출할 수 있습니다.
- REST API – LangChain과 같은 프레임워크를 위한 일반 HTTP/WebSocket 엔드포인트.
결과물은 에이전트가(describe 또는 스크린샷으로) 검사하고, 요소별로 수정하고, 마지막에 .excalidraw 파일로 내보낼 수 있는 라이브이며 편집 가능한 다이어그램입니다. 이 파일은 소스 코드 옆이나 Obsidian 볼트에 저장할 수 있습니다.
누가 사용하면 좋을까
- 코딩 어시스턴트 – 개발 워크플로우의 일부로 아키텍처 다이어그램, 순서도, UI 목업을 생성해야 하는 도구.
- 팀 – 다이어그램 파일을 코드와 함께 버전 관리하려는 팀(예:
.excalidraw파일을 Git에 커밋). - Obsidian 사용자 – 다이어그램을 볼트에 보관하면서 완전한 편집 가능성을 유지하려는 사용자.
- 맞춤형 AI 에이전트 도구체인을 구축하는 사람 – MCP 도구나 REST API를 호출할 수 있는 도구체인을 구축하는 개발자.
주요 기능(README에서 발췌)
| 기능 | 설명 |
|---|---|
| 로컬 캔버스 서버 | http://127.0.0.1:3000에서 Excalidraw 웹 UI를 실행하고 실시간 WebSocket 동기화를 제공. 외부 서비스 불필요. |
| CLI 우선 설계 | 모든 기능이 합성 가능한 명령(add, apply, query, screenshot, export, mermaid, snapshot, arrange, share 등)으로 노출. JSON을 표준 출력으로 출력하고 종료 코드로 성공/실패를 나타냅니다. |
| MCP 통합 | MCP 프로토콜 리비전 2026-07-28 구현. 26개의 도구로 모든 MCP 클라이언트(Claude Desktop, Cursor, Codex CLI, Antigravity 등)가 stdio를 통해 캔버스를 조작할 수 있습니다. |
| REST API | LangChain 및 사용자 정의 스크립트를 위한 간단한 HTTP 엔드포인트. |
| 요소 수준 CRUD | 개별 도형, 화살표, 텍스트, 그룹, 잠금 등을 생성, 읽기, 업데이트, 삭제할 수 있습니다. |
| 반복적 개선 | 에이전트는 describe로 장면을 확인하고, screenshot을 찍고, 레이아웃을 조정하고, 다이어그램이 완성될 때까지 반복할 수 있습니다. |
| 내보내기 / 가져오기 | 네이티브 .excalidraw JSON 또는 Obsidian 호환 .excalidraw.md로 내보내기. 압축 파일을 포함한 두 형식 모두 가져오기 지원. |
| 결정적 내보내기 | ID, 시드, 키 순서가 안정적이어서 변경되지 않은 다이어그램은 동일한 파일을 생성하므로 Git diff가 지저분해지지 않습니다. |
| Mermaid 변환 | Mermaid 구문을 붙여넣으면 생성된 다이어그램이 기존 캔버스에 병합됩니다. |
| 뷰포트 제어 | 선택한 요소에 확대/축소, 이동, 맞춤 명령. |
| 공유 | 선택적으로 암호화된 업로드를 excalidraw.com에 수행하여 공유 가능한 URL을 생성합니다. |
| Docker 이미지 | 손쉬운 배포를 위한 사전 빌드 컨테이너(ghcr.io/yctimlin/mcp_excalidraw). |
| 에이전트 스킬 번들 | 이식 가능한 스킬(skills/excalidraw-skill/)로, 단일 install-skill 명령으로 에이전트의 스킬 디렉토리에 설치할 수 있습니다. |
| 제로 설정 자동 시작 | CLI 명령과 MCP 서버는 캔버스가 실행 중이 아니면 자동으로 시작합니다(EXCALIDRAW_NO_AUTOSTART=1로 비활성화). |
빠른 시작
# 설치 및 캔버스 시작(첫 그리기 명령에서 자동 시작)
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 선택 사항 – 스크린샷/Mermaid에 필요
# 두 개의 상자와 화살표 추가(JSON을 표준 입력으로 전달)
echo '[
{"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"}
]' | npx -y mcp-excalidraw-server add
# 에이전트가 다이어그램을 볼 수 있게 하기
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 버전 관리를 위해 내보내기
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw
동일한 명령은 MCP 호환 클라이언트에서 또는 HTTP를 통해서도 호출할 수 있습니다.
알려진 제한 사항 / 미해결 문제(README에서 발췌)
- 서버는 기본적으로
127.0.0.1에만 바인딩됩니다. 외부에 노출하려면 사용자가 자체 방화벽이나 리버스 프록시를 설정해야 합니다 – 내장 인증은 없습니다. - 일부 작업(예:
screenshot,mermaid변환)은 클라이언트 측 Excalidraw UI에 의존하므로 브라우저 탭이 열려 있어야 합니다. - README에는 "알려진 문제 / TODO" 섹션이 몇 개 있지만 구체적인 버그는 나열되어 있지 않습니다. 최신 상태는 이슈 트래커를 확인하세요.
유지 관리자
이 저장소는 yctimlin이 소유하고 있으며 npm에 mcp-excalidraw-server로 게시되어 있습니다(MIT 라이선스). 지속적 통합은 푸시할 때마다 테스트를 실행하고 Docker 이미지를 빌드합니다.
TL;DR
mcp-excalidraw-server는 AI 코딩 에이전트에게 프로그래밍 방식으로 제어할 수 있는 실제로 편집 가능한 그리기 표면을 제공합니다. 간단한 CLI, MCP stdio 서버 또는 REST API를 통해 작동하며, 다이어그램을 버전 관리된 .excalidraw 파일로 저장합니다. 이는 LLM이 생성한 아키텍처 아이디어와 구체적이고 편집 가능한 다이어그램 사이의 실용적인 다리 역할을 합니다.
관련
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트
- 프로젝트