excalidraw-architect-mcp
Excalidraw Architect MCP
익숙하지 않고 복잡한 코드베이스를 이해하려고 노력하는 것은 인지적 과부하를 관리하고 모든 것이 어떻게 맞물려 돌아가는지 상상해야 하기에 끊임없는 고군분투였습니다.
문제점
코드베이스에 온보딩하거나, 새로운 시스템을 설계하거나, 기존 아키텍처를 문서화할 때, 시각적 다이어그램은 수 페이지의 텍스트로는 전달할 수 없는 내용을 단 몇 초 만에 전달합니다. 하지만 오늘날의 선택지들은 그리 좋지 않습니다. Mermaid 다이어그램은 생성하기는 빠르지만 기능이 제한적입니다. 노드를 드래그하여 위치를 변경하거나 컴포넌트를 시각적으로 그룹화할 수 없습니다. Excalidraw는 이러한 문제를 해결하지만, LLM이 Excalidraw를 직접 생성하려고 하면 좌표를 환각(hallucinate)하여 상자가 겹치고 화살표가 엉키며, 결국 다이어그램을 수동으로 수정하게 됩니다.
Related MCP server: mermaid-to-excalidraw-mcp
해결책
excalidraw-architect-mcp는 *무엇(what)*과 *어디(where)*를 분리합니다. AI는 구조에 집중하고, 엔진은 적절한 그래프 레이아웃 알고리즘을 사용하여 픽셀 계산을 처리합니다.
LLM이 컴포넌트와 연결을 설명하면, MCP가 적절한 그래프 레이아웃 알고리즘을 사용하여 레이아웃, 스타일링 및 렌더링을 처리합니다. 50개 이상의 기술(Kafka, PostgreSQL, Redis 등)이 자동으로 스타일링되며, 자연어로 다이어그램을 반복적으로 편집할 수 있고("DB 앞에 캐시 추가"), Cursor/Windsurf에서 API 키 없이 완전히 오프라인으로 실행됩니다.
항상 완벽한 레이아웃 - 적응형 간격이 적용된 Sugiyama 알고리즘; 겹치는 상자 없음
아키텍처 인식 스타일링 - "Kafka"라고 말하면 일반적인 직사각형이 아닌 스트림 스타일의 노드를 얻습니다.
다이어그램과 대화 - 자연어를 사용하여 기존 다이어그램의 컴포넌트를 추가, 제거 또는 재연결합니다.
허브 노드 시각화 - 게이트웨이와 로드 밸런서가 연결된 서비스에 맞춰 자동으로 확장됩니다.
SVG 및 PNG로 내보내기 - 브라우저 없이도 모든
.excalidraw파일을 휴대용 이미지로 변환합니다.
작동 방식
아래의 모든 프레임은 수동 위치 지정 없이 이 MCP를 사용하여 AI가 완전히 생성한 것입니다.
전자상거래 플랫폼 아키텍처

결제 처리 흐름

사용 사례
새로운 코드베이스 온보딩 - 마이크로서비스를 가리키면 코드 한 줄 읽지 않고도 상위 수준의 아키텍처 다이어그램을 얻을 수 있습니다. 세부 정보가 필요할 때는 클래스 세트를 가리켜 하위 수준의 흐름 다이어그램을 얻으세요.
브레인스토밍 및 시스템 설계 - 새로운 서비스를 화이트보드에 그리거나 트레이드오프를 논의할 때, 진행하면서 아키텍처를 시각화하도록 요청하세요. 처음부터 다시 그릴 필요 없이 "여기에 캐시 추가" 또는 "Kafka를 SQS로 교체"라고 말하여 반복 수정하세요.
살아있는 문서화 -
.excalidraw파일을 저장소에 넣고 시스템이 발전함에 따라 자연어로 업데이트하세요. 6번의 스프린트 전의 낡은 다이어그램은 이제 그만 사용하세요.
빠른 시작
설치
pip install excalidraw-architect-mcpPNG 내보내기 지원(SVG는 즉시 작동):
pip install excalidraw-architect-mcp[png]또는 설치 없이 실행(uv 필요):
uvx excalidraw-architect-mcpIDE에서 MCP 구성
Cursor - .cursor/mcp.json에 추가:
{
"mcpServers": {
"excalidraw-architect": {
"command": "excalidraw-architect-mcp",
"transport": "stdio"
}
}
}Claude Code - 이 한 줄 명령어를 실행하세요:
claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope user또는 프로젝트 루트의 .mcp.json에 수동으로 추가:
{
"mcpServers": {
"excalidraw-architect": {
"type": "stdio",
"command": "excalidraw-architect-mcp"
}
}
}Windsurf / 기타 IDE - 동일한 패턴; stdio를 통해 excalidraw-architect-mcp 명령을 가리키세요.
다이어그램 디자인 기술 설치(권장)
이 저장소에는 AI에게 최상의 결과를 얻기 위한 다이어그램 구조화 방법(노드 수 제한, 토폴로지 규칙, 엣지 라벨 가이드라인 및 일반적인 패턴)을 가르치는 Diagram Design Skill이 포함되어 있습니다.
Cursor 사용자:
mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \
curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \
https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md기타 IDE: SKILL.md 파일을 다운로드하여 IDE의 프롬프트 컨텍스트나 시스템 지침에 추가하세요.
AI는 다이어그램을 생성할 때 자동으로 기술을 습득하고 적용합니다. 노드 제한 조정, 자신만의 패턴 추가, 스타일링 가이드라인 조정 등 선호도에 맞게 규칙을 자유롭게 수정하세요.
다이어그램 복잡성에 대한 참고 사항: 컴포넌트와 연결 수가 증가함에 따라 다이어그램은 읽기 어려워집니다. 이는 자동 레이아웃뿐만 아니라 사람이 직접 그릴 때도 마찬가지입니다. 최상의 결과를 얻으려면 아키텍처 다이어그램은 6-15개 노드, 상세 흐름은 10-25개 노드를 목표로 하세요. 시스템이 더 크다면 모든 것을 하나에 담으려 하지 말고 여러 개의 집중된 다이어그램으로 나누세요.
사용 방법
AI IDE에 자연스럽게 요청하세요:
"이 코드베이스의 상위 수준 아키텍처 다이어그램을 만들어줘"
"API 게이트웨이, 인증 서비스, 사용자 서비스, 주문 서비스, PostgreSQL, Redis 캐시, Kafka 이벤트 버스가 포함된 마이크로서비스 시스템의 아키텍처 다이어그램을 만들어줘"
"이 mermaid 다이어그램을 excalidraw 다이어그램으로 변환해줘"
"상위 수준 아키텍처 다이어그램의 주문 서비스 앞에 캐싱 계층을 추가해줘"
"아키텍처 다이어그램을 SVG로 내보내줘"
"다이어그램을 3배 해상도의 PNG로 내보내줘"
AI는 관계 맵과 함께 MCP 도구를 호출합니다. MCP는 레이아웃, 스타일링 및 출력을 처리합니다. 결과로 생성된 .excalidraw 파일을 Excalidraw VS Code 확장 프로그램으로 열거나 excalidraw.com으로 드래그하세요.
기능
자동 레이아웃 엔진
다음과 같은 Sugiyama 계층 레이아웃 알고리즘을 사용합니다:
적응형 레이어 간격 - 엣지 라벨 길이에 따라 간격 조정
허브 노드 확장 - 게이트웨이/로드 밸런서가 연결된 서비스에 맞춰 확장
장애물 인식 엣지 라우팅 - 화살표가 중간 노드를 통과하지 않고 우회하도록 곡선 처리
연결되지 않은 컴포넌트 스태킹 - 별도의 서브그래프(예: 모니터링 스택)가 겹치지 않게 배치
컴포넌트 라이브러리
자동 시각적 스타일링이 포함된 50개 이상의 기술 매핑:
카테고리 | 기술 |
데이터베이스 | PostgreSQL, MySQL, MongoDB, DynamoDB, Cassandra, ClickHouse, SQLite, CockroachDB |
메시지 큐 | Kafka, RabbitMQ, SQS, Redis Streams, NATS |
캐시 | Redis, Memcached, Varnish |
로드 밸런서 | Nginx, HAProxy, ALB/ELB, Traefik, Envoy |
컴퓨팅 | Docker, Kubernetes, Lambda, ECS, Fargate |
스토리지 | S3, GCS, Azure Blob, MinIO |
API | REST, GraphQL, gRPC, WebSocket |
CDN | CloudFront, Cloudflare |
모니터링 | Prometheus, Grafana, Datadog, ELK |
클라이언트 | Browser, Mobile, Desktop, CLI |
상태 유지 편집
다이어그램 메타데이터가 .excalidraw 파일에 포함되어 있습니다. AI에게 요청하세요:
"기존 다이어그램의 데이터베이스 앞에 Redis 캐시를 추가해줘"
MCP가 현재 상태를 읽고, 수정을 적용한 뒤 적절한 레이아웃으로 다시 렌더링합니다.
Mermaid 변환
이미 Mermaid 순서도가 있나요? 변환하세요:
"이 Mermaid 다이어그램을 Excalidraw로 변환해줘" (Mermaid 구문 붙여넣기)
이미지 내보내기
모든 .excalidraw 다이어그램을 휴대용 이미지로 내보내세요. 브라우저, Excalidraw 앱 또는 Node.js가 필요하지 않습니다.
SVG - 추가 종속성 없음; 직사각형, 타원, 다이아몬드, 텍스트(다중 라인 포함), 화살촉이 있는 화살표를 처리하는 순수 Python 렌더러 사용
PNG - 선택적
cairosvg패키지 필요 (pip install excalidraw-architect-mcp[png]); 구성 가능한 해상도 배율 지원(기본값 2배)
"아키텍처 다이어그램을 SVG로 내보내줘"
MCP 도구
도구 | 설명 |
| 구조화된 노드/연결 데이터로 새 다이어그램 생성 |
| Mermaid 순서도 구문을 |
| 기존 다이어그램의 노드 및 연결 추가/제거/업데이트 |
| 현재 다이어그램 상태 읽기 (수정 전 호출) |
|
|
기여
자세한 내용은 CONTRIBUTING.md를 참조하세요.
라이선스
MIT - LICENSE 참조.
Available Tools
26 toolscreate_diagramA
Create a new Excalidraw diagram of any supported type.
Two input modes:
Graph types (
architecture,flowchart) - passnodesandconnections. The tool handles layout, styling, and rendering; no coordinates needed.Typed diagrams (every other type) - pass
diagram_typeand aspecobject shaped for that type. Calllist_diagram_typesto choose a type andget_diagram_schemato see its spec shape.
Inputs: output_path (required), spec, nodes, theme, +3 more. Returns: result
export_diagramA
Export an .excalidraw file to SVG or PNG image.
Converts an existing .excalidraw diagram into a portable image file without requiring a browser or the Excalidraw application.
Inputs: input_path (required), output_path (required), scale, format. Returns: result
get_diagram_infoA
Get a structured summary of an existing Excalidraw diagram.
Call this BEFORE modify_diagram to understand what nodes and connections currently exist. The summary includes node ids, labels, component types, and the full connection topology.
Inputs: file_path (required). Returns: result
get_diagram_schemaA
Get the JSON schema and selection guidance for one diagram type.
Call this before passing a spec to create_diagram for a type you have
not used yet, so the payload matches on the first attempt.
Inputs: diagram_type (required). Returns: result
kg_add_serviceB
Add or update a service in the knowledge graph.
Inputs: id (required), tags, label, links, +6 more. Returns: result
kg_diffB
Show how the architecture changed since a git ref (default HEAD).
Compares the current knowledge file against its version at ref.
Inputs: ref, graph_path. Returns: result
kg_driftA
Detect drift between the declared architecture and Python imports under code_root.
Best-effort: treats each top-level package as a service and infers edges from imports. Reports undocumented and possibly-stale dependencies.
Inputs: code_root (required), graph_path. Returns: result
kg_exportC
Export the knowledge graph to another format.
Inputs: format, graph_path, output_path. Returns: result
kg_importB
Import an existing .excalidraw diagram's services into the knowledge graph.
Bootstraps the graph from diagrams you already created with this tool.
Inputs: excalidraw_path (required), graph_path. Returns: result
kg_infoA
Summarize the whole knowledge graph: services, domains, and topology.
Call this before mutating the graph to reason about current state.
Inputs: graph_path. Returns: result
kg_initB
Create a new architecture knowledge graph file (markdown).
The knowledge graph is the persistent source of truth for your system's services and dependencies. Diagrams are rendered from it.
Inputs: title, direction, overwrite, graph_path. Returns: result
kg_linkA
Add a directed dependency: from_id depends on / calls to_id.
Both services must already exist (add them with kg_add_service first).
style is one of solid/dashed/dotted/thick.
Inputs: to_id (required), from_id (required), label, style, +1 more. Returns: result
kg_lintA
Architecture health check: cycles, single points of failure, orphans, dangling references, and (optionally) unowned services.
Inputs: graph_path, check_owners. Returns: result
kg_onboarding_docC
Generate a human onboarding guide (entry points, hubs, domains) from the graph.
Inputs: graph_path, output_path. Returns: result
kg_pathC
Trace the shortest dependency path between two services.
Inputs: to_id (required), from_id (required), graph_path. Returns: result
kg_remove_serviceC
Remove a service and all dependencies touching it.
Inputs: id (required), graph_path. Returns: result
kg_renderC
Render the entire architecture to an .excalidraw file.
Inputs: output_path (required), theme, graph_path. Returns: result
kg_render_aroundB
Render a service plus everything within depth hops of it.
direction: "downstream" (its dependencies), "upstream" (its
dependents), or "both".
Inputs: depth (required), service_id (required), output_path (required), theme, +2 more. Returns: result
kg_render_domainC
Render only the services belonging to one domain.
Inputs: domain (required), output_path (required), theme, graph_path. Returns: result
kg_render_viewC
Render a focused diagram of just the given services (induced subgraph).
Inputs: node_ids (required), output_path (required), theme, graph_path. Returns: result
kg_set_domainC
Assign a service to a domain (optionally set the domain's display label).
Inputs: domain (required), service_id (required), label, graph_path. Returns: result
kg_unlinkC
Remove the dependency from_id -> to_id.
Inputs: to_id (required), from_id (required), graph_path. Returns: result
list_diagram_typesA
List every supported diagram type with guidance on when to use it.
Call this BEFORE create_diagram when the right diagram type isn't obvious. Picking the wrong type is the most common way a diagram fails - a swimlane drawn as a flowchart loses the handoffs that were the point.
Two rules worth applying whatever you pick:
Target density ~4/10. Above 9 nodes it is probably two diagrams.
Mark only 1-2 elements "focal": true. The accent color is a signal, and using it everywhere destroys it.
Returns: A table of type -> family, when to use it, and when not to.
Inputs: no named parameters. Returns: result
mermaid_to_excalidrawA
Convert Mermaid flowchart syntax into an Excalidraw diagram.
Supports the mermaid flowchart subset that AI agents commonly generate:
Directions: graph TD, LR, BT, RL
Node shapes: [text], {text}, ((text)), ([text])
Edge types: -->, ---, -.-> ==> with |label|
Subgraphs: subgraph Title ... end
Component types are auto-detected from node labels (e.g., a node labeled "PostgreSQL DB" automatically gets database styling).
Inputs: output_path (required), mermaid_syntax (required), theme. Returns: result
modify_diagramA
Modify an existing Excalidraw diagram created by this tool.
Supports iterative editing: add components, remove nodes, update labels, and rewire connections - without recreating the entire diagram.
IMPORTANT: Call get_diagram_info first to understand the current diagram state before making modifications.
For typed diagrams (sequence, pyramid, bar, swimlane, ...) there is a single operation:
{"op": "update_spec", "patch": {"tiers": [...], "title": "New title"}}The patch is deep-merged into the stored spec and the diagram re-rendered. Lists are replaced wholesale, so send the complete list to change one entry. The node/connection operations below apply to architecture and flowchart diagrams only.
Inputs: file_path (required), operations (required), theme. Returns: result
whats_connected_toA
Impact analysis: what breaks if service_id fails?
Reports direct dependents, the full transitive upstream blast radius, and what the service itself depends on.
Inputs: service_id (required), graph_path. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools target clearly distinct operations, and descriptions separate KG management, diagram creation, and analysis queries well. The four kg_render* variants (full, domain, view, around) are close enough to cause some misselection risk, though each has a well-defined scope.
The kg_ prefix provides a strong, predictable pattern for graph operations, and most diagram tools use clear verb_noun names. Minor exceptions like whats_connected_to and mermaid_to_excalidraw break the pattern, but overall the naming is disciplined and readable.
At 26 tools, the server sits just above the heavy band, and the kg_render_domain/view/around trio could plausibly be consolidated into one parameterized render operation. The breadth is partly justified by spanning diagram authoring and knowledge-graph management, but the surface is still large.
The toolset covers the full lifecycle for both the knowledge graph and diagrams: init, add/update/remove, link/unlink, query, render, export, plus analysis features like lint, drift, diff, impact, and path tracing. The only missing operations are non-essential file-management tasks like deleting a rendered diagram.
Maintenance
Related MCP Connectors
Collaborative whiteboard MCP server — create objects, connectors, C4 diagrams, and manage boards
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server for Excalidraw diagram creation and headless rendering, enabling interactive canvas editing and automated SVG/PNG export via Playwright.41MIT
- AlicenseAqualityDmaintenanceMCP server that converts Mermaid diagrams to styled Excalidraw files, saving them directly to disk without token overhead.2MIT
- FlicenseAqualityBmaintenanceAn MCP server that generates standalone SVG architecture diagrams from text descriptions, running entirely on your machine with no dependencies or network access.8-
- AlicenseAqualityDmaintenanceMCP server for generating and editing architecture diagrams from natural language or code, supporting formats like Terraform, docker-compose, Kubernetes, SQL, Mermaid, and PlantUML.2MIT