Excalidraw Architect MCP

👁 PyPI
👁 Cursor Directory
👁 License: MIT

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: AI Charts

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 .excalidraw en 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

👁 Demostración de plataforma de comercio electrónico

Flujo de procesamiento de pagos

👁 Demostración de 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 .excalidraw en 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-mcp

Para 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-mcp

Configura 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 user

O 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.md

Para 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:

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

Contribución

Consulta CONTRIBUTING.md para más detalles.

Licencia

MIT - consulta LICENSE.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• create_diagramA
• export_diagramA
• get_diagram_infoA
• kg_add_serviceB
• kg_diffB
• kg_driftA
• kg_exportC
• kg_importB