excalidraw-architect-mcp
Excalidraw Architect MCP
Ha sido una lucha constante intentar entender bases de código complejas y desconocidas: gestionar la sobrecarga cognitiva e intentar imaginar cómo encaja todo.
El problema
Cuando te incorporas a una base de código, diseñas un nuevo sistema o documentas una arquitectura existente, un diagrama visual comunica en segundos lo que páginas de texto no pueden. Pero las opciones actuales no son buenas. Los diagramas de Mermaid son rápidos de generar pero tienen capacidades limitadas: no puedes arrastrar un nodo para reposicionarlo ni agrupar componentes visualmente. Excalidraw resuelve estos problemas, pero cuando los LLM intentan generar Excalidraw directamente, alucinan con las coordenadas: las cajas se superponen, las flechas se enredan y terminas arreglando el diagrama manualmente.
Related MCP server: mermaid-to-excalidraw-mcp
La solución
excalidraw-architect-mcp separa el qué del dónde: la IA se centra en la estructura, el motor se encarga de los cálculos de píxeles.
Tu LLM describe los componentes y las conexiones, y el MCP maneja el diseño, el estilo y el renderizado utilizando un algoritmo de diseño de grafos adecuado. Más de 50 tecnologías (Kafka, PostgreSQL, Redis, etc.) obtienen estilos automáticos, puedes editar diagramas de forma iterativa con lenguaje natural ("añade una caché delante de la base de datos") y se ejecuta completamente sin conexión en Cursor/Windsurf; no se necesitan claves API.
Diseños perfectos siempre - Algoritmo de Sugiyama con espaciado adaptativo; sin cajas superpuestas
Estilos conscientes de la arquitectura - di "Kafka" y obtén un nodo con estilo de flujo, no un rectángulo genérico
Habla con tus diagramas - añade, elimina o reconecta componentes en un diagrama existente con lenguaje natural
Visualización de nodos hub - las puertas de enlace y los balanceadores de carga se estiran automáticamente para abarcar sus servicios conectados
Exportación a SVG y PNG - convierte cualquier archivo
.excalidrawen una imagen portátil, sin necesidad de navegador
Véalo en acción
Cada fotograma a continuación es generado completamente por IA usando este MCP: cero posicionamiento manual.
Arquitectura de plataforma de comercio electrónico

Flujo de procesamiento de pagos

Casos de uso
Incorporación a una nueva base de código - apúntalo a un microservicio y obtén un diagrama de arquitectura de alto nivel sin leer una sola línea de código. Apúntalo a un conjunto de clases para un diagrama de flujo de bajo nivel cuando necesites los detalles.
Lluvia de ideas y diseño de sistemas - cuando estés diseñando un nuevo servicio o debatiendo compensaciones, pídele que visualice la arquitectura a medida que avanzas. Itera diciendo "añade una caché aquí" o "cambia Kafka por SQS" en lugar de volver a dibujar desde cero.
Documentación que permanece viva - coloca el archivo
.excalidrawen tu repositorio y actualízalo con lenguaje natural a medida que el sistema evoluciona. No más diagramas obsoletos de hace seis sprints.
Inicio rápido
Instalación
pip install excalidraw-architect-mcpPara soporte de exportación PNG (SVG funciona de inmediato):
pip install excalidraw-architect-mcp[png]O ejecútalo sin instalar (requiere uv):
uvx excalidraw-architect-mcpConfigura MCP en tu IDE
Cursor - Añade a .cursor/mcp.json:
{
"mcpServers": {
"excalidraw-architect": {
"command": "excalidraw-architect-mcp",
"transport": "stdio"
}
}
}Claude Code - Ejecuta esta línea:
claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope userO añádelo manualmente a .mcp.json en la raíz de tu proyecto:
{
"mcpServers": {
"excalidraw-architect": {
"type": "stdio",
"command": "excalidraw-architect-mcp"
}
}
}Windsurf / Otros IDEs - Mismo patrón; apunta al comando excalidraw-architect-mcp a través de stdio.
Instala la habilidad de diseño de diagramas (recomendado)
Este repositorio incluye una Habilidad de diseño de diagramas que enseña a la IA cómo estructurar diagramas para obtener los mejores resultados: límites de recuento de nodos, reglas de topología, pautas de etiquetas de borde y patrones comunes.
Para usuarios de 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.mdPara otros IDEs: Descarga el archivo SKILL.md y añádelo al contexto de instrucciones o instrucciones del sistema de tu IDE.
La IA recogerá automáticamente la habilidad y la aplicará al generar diagramas. Siéntete libre de modificar las reglas para adaptarlas a tus preferencias: ajusta los límites de nodos, añade tus propios patrones o ajusta las pautas de estilo.
Una nota sobre la complejidad del diagrama: A medida que crece el número de componentes y conexiones, los diagramas inevitablemente se vuelven más difíciles de leer; esto también es cierto para los humanos que dibujan a mano, no solo para el diseño automatizado. Para obtener los mejores resultados, apunta a 6-15 nodos en diagramas de arquitectura y 10-25 nodos en flujos detallados. Si tu sistema es más grande, divídelo en múltiples diagramas enfocados en lugar de amontonar todo en uno.
Úsalo
Simplemente pregúntale a tu IDE de IA de forma natural:
"Crea un diagrama de arquitectura de alto nivel de esta base de código"
"Crea un diagrama de arquitectura para un sistema de microservicios con un API Gateway, Auth Service, User Service, Order Service, PostgreSQL, caché Redis y bus de eventos Kafka"
"Convierte este diagrama de mermaid a diagrama de excalidraw"
"Añade una capa de caché al Order Service en el diagrama de arquitectura de alto nivel"
"Exporta el diagrama de arquitectura a SVG"
"Exporta el diagrama como un PNG a resolución 3x"
La IA llama a la herramienta MCP con el mapa de relaciones. El MCP maneja el diseño, el estilo y la salida. Abre el archivo .excalidraw resultante con la extensión de Excalidraw para VS Code o arrástralo a excalidraw.com.
Características
Motor de diseño automático
Utiliza el algoritmo de diseño jerárquico de Sugiyama con:
Brechas de capa adaptativas - el espaciado se ajusta según la longitud de la etiqueta del borde
Estiramiento de nodos hub - las puertas de enlace/balanceadores de carga se estiran para abarcar los servicios conectados
Enrutamiento de bordes consciente de obstáculos - las flechas se curvan alrededor de los nodos intermedios en lugar de atravesarlos
Apilamiento de componentes desconectados - los subgrafos separados (p. ej., pila de monitoreo) se colocan sin superposición
Biblioteca de componentes
Más de 50 mapeos de tecnología con estilo visual automático:
Categoría | Tecnologías |
Base de datos | PostgreSQL, MySQL, MongoDB, DynamoDB, Cassandra, ClickHouse, SQLite, CockroachDB |
Cola de mensajes | Kafka, RabbitMQ, SQS, Redis Streams, NATS |
Caché | Redis, Memcached, Varnish |
Balanceador de carga | Nginx, HAProxy, ALB/ELB, Traefik, Envoy |
Cómputo | Docker, Kubernetes, Lambda, ECS, Fargate |
Almacenamiento | S3, GCS, Azure Blob, MinIO |
API | REST, GraphQL, gRPC, WebSocket |
CDN | CloudFront, Cloudflare |
Monitoreo | Prometheus, Grafana, Datadog, ELK |
Cliente | Navegador, Móvil, Escritorio, CLI |
Edición con estado
Los metadatos del diagrama están incrustados en el archivo .excalidraw. Pregúntale a la IA:
"Añade una caché Redis delante de la base de datos en el diagrama existente"
El MCP lee el estado actual, aplica la modificación y vuelve a renderizar con el diseño adecuado.
Conversión de Mermaid
¿Ya tienes un diagrama de flujo de Mermaid? Conviértelo:
"Convierte este diagrama de Mermaid a Excalidraw" (pega tu sintaxis de Mermaid)
Exportación de imágenes
Exporta cualquier diagrama .excalidraw a una imagen portátil: no se requiere navegador, aplicación Excalidraw ni Node.js.
SVG - cero dependencias adicionales; utiliza un renderizador de Python puro que maneja rectángulos, elipses, diamantes, texto (incluido multilínea) y flechas con puntas de flecha
PNG - requiere el paquete opcional
cairosvg(pip install excalidraw-architect-mcp[png]); admite un multiplicador de resolución configurable (predeterminado 2×)
"Exporta el diagrama de arquitectura como un SVG"
Herramientas MCP
Herramienta | Descripción |
| Crea un nuevo diagrama a partir de datos estructurados de nodos/conexiones |
| Convierte la sintaxis de diagrama de flujo de Mermaid a |
| Añade/elimina/actualiza nodos y conexiones en un diagrama existente |
| Lee el estado actual del diagrama (llamar antes de modificar) |
| Exporta |
Contribución
Consulta CONTRIBUTING.md para más detalles.
Licencia
MIT - consulta 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