excalidraw-architect-mcp
Excalidraw Architect MCP
Постоянная борьба с пониманием незнакомых и сложных кодовых баз — это управление когнитивной нагрузкой и попытки представить, как все части соединяются вместе.
Проблема
Когда вы погружаетесь в кодовую базу, проектируете новую систему или документируете существующую архитектуру, визуальная диаграмма за секунды передает то, что невозможно описать страницами текста. Но современные варианты не идеальны. Диаграммы Mermaid быстро создаются, но имеют ограниченные возможности — вы не можете перетащить узел, чтобы изменить его положение, или визуально сгруппировать компоненты. Excalidraw решает эти проблемы, но когда LLM пытаются генерировать Excalidraw напрямую, они галлюцинируют с координатами — блоки перекрываются, стрелки запутываются, и в итоге вы исправляете диаграмму вручную.
Related MCP server: mermaid-to-excalidraw-mcp
Решение
excalidraw-architect-mcp отделяет что от где — ИИ фокусируется на структуре, а движок берет на себя математику пикселей.
Ваша LLM описывает компоненты и связи, а MCP управляет компоновкой, стилизацией и рендерингом с использованием правильного алгоритма построения графов. Более 50 технологий (Kafka, PostgreSQL, Redis и т. д.) получают автоматическое оформление, вы можете итеративно редактировать диаграммы на естественном языке («добавь кэш перед БД»), и все это работает полностью офлайн в Cursor/Windsurf — ключи API не нужны.
Идеальная компоновка каждый раз — алгоритм Сугиямы с адаптивными отступами; никаких перекрывающихся блоков
Стилизация с учетом архитектуры — скажите «Kafka», и вы получите узел в стиле потока данных, а не обычный прямоугольник
Общайтесь со своими диаграммами — добавляйте, удаляйте или переподключайте компоненты на существующей диаграмме с помощью естественного языка
Визуализация узлов-концентраторов — шлюзы и балансировщики нагрузки автоматически растягиваются, охватывая подключенные к ним сервисы
Экспорт в SVG и PNG — конвертируйте любой файл
.excalidrawв портативное изображение, браузер не требуется
Посмотрите на это в действии
Каждый кадр ниже полностью сгенерирован ИИ с использованием этого MCP — без ручного позиционирования.
Архитектура платформы электронной коммерции

Поток обработки платежей

Варианты использования
Погружение в новую кодовую базу — укажите на микросервис и получите высокоуровневую архитектурную диаграмму, не читая ни строчки кода. Укажите на набор классов для низкоуровневой диаграммы потока, когда вам нужны детали.
Мозговой штурм и проектирование систем — когда вы рисуете на доске новую услугу или обсуждаете компромиссы, попросите визуализировать архитектуру по ходу дела. Вносите изменения, говоря «добавь сюда кэш» или «замени Kafka на SQS», вместо того чтобы перерисовывать все с нуля.
Документация, которая остается актуальной — добавьте файл
.excalidrawв свой репозиторий и обновляйте его на естественном языке по мере развития системы. Больше никаких устаревших диаграмм шестимесячной давности.
Быстрый старт
Установка
pip install excalidraw-architect-mcpДля поддержки экспорта в PNG (SVG работает «из коробки»):
pip install excalidraw-architect-mcp[png]Или запустите без установки (требуется uv):
uvx excalidraw-architect-mcpНастройка MCP в вашей IDE
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 — тот же принцип; укажите на команду excalidraw-architect-mcp через stdio.
Установите навык проектирования диаграмм (рекомендуется)
Этот репозиторий включает 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.
ИИ автоматически подхватит этот навык и применит его при создании диаграмм. Не стесняйтесь изменять правила в соответствии со своими предпочтениями — настраивайте лимиты узлов, добавляйте свои шаблоны или корректируйте рекомендации по стилю.
Примечание о сложности диаграмм: По мере увеличения количества компонентов и связей диаграммы неизбежно становятся труднее для чтения — это верно и для людей, рисующих от руки, а не только для автоматической компоновки. Для достижения наилучших результатов стремитесь к 6-15 узлам на архитектурных диаграммах и 10-25 узлам на подробных схемах потоков. Если ваша система больше, разбейте ее на несколько сфокусированных диаграмм, а не пытайтесь втиснуть все в одну.
Использование
Просто попросите свой ИИ-IDE естественным языком:
"Create a high-level architecture diagram of this codebase"
"Create an architecture diagram for a microservices system with an API Gateway, Auth Service, User Service, Order Service, PostgreSQL, Redis cache, and Kafka event bus"
"Convert this mermaid diagram to excalidraw diagram"
"Add a Caching layer to the Order Service in the High Level architecture diagram"
"Export the architecture diagram to SVG"
"Export the diagram as a PNG at 3x resolution"
ИИ вызывает инструмент MCP с картой связей. MCP управляет компоновкой, стилем и выводом. Откройте полученный файл .excalidraw с помощью расширения Excalidraw для VS Code или перетащите его в excalidraw.com.
Функции
Движок автоматической компоновки
Использует иерархический алгоритм компоновки Сугиямы с:
Адаптивными зазорами между слоями — расстояние регулируется в зависимости от длины подписи ребра
Растяжением узлов-концентраторов — шлюзы/балансировщики нагрузки растягиваются, охватывая подключенные сервисы
Маршрутизацией ребер с учетом препятствий — стрелки огибают промежуточные узлы, а не проходят сквозь них
Стекированием несвязных компонентов — отдельные подграфы (например, стек мониторинга) размещаются без перекрытий
Библиотека компонентов
Более 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. Попросите ИИ:
"Add a Redis cache in front of the database in the existing diagram"
MCP считывает текущее состояние, применяет модификацию и перерисовывает с правильной компоновкой.
Конвертация Mermaid
Уже есть блок-схема Mermaid? Конвертируйте ее:
"Convert this Mermaid diagram to Excalidraw" (вставьте ваш синтаксис Mermaid)
Экспорт изображений
Экспортируйте любую диаграмму .excalidraw в портативное изображение — браузер, приложение Excalidraw или Node.js не требуются.
SVG — ноль дополнительных зависимостей; использует чисто Python-рендерер, который обрабатывает прямоугольники, эллипсы, ромбы, текст (включая многострочный) и стрелки с наконечниками
PNG — требует опциональный пакет
cairosvg(pip install excalidraw-architect-mcp[png]); поддерживает настраиваемый множитель разрешения (по умолчанию 2×)
"Export the architecture diagram as an 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