David Poza
Scientia potentia est

Diagramas con IA: cómo usar el MCP oficial de draw.io

17 de noviembre 2026Comentariosherramientas desarrolloDavid Poza SuárezComentarios

Si habéis leído el artículo de control de herramientas con visión artificial habréis visto que tiene muchos diagramas: contexto, contenedores, componentes, secuencia, pipeline... Hacerlos me llevó casi tanto como escribir el texto. Y es que dibujar diagramas de arquitectura es una de esas tareas que todos sabemos que hay que hacer, que aportan muchísimo, y que todos procrastinamos porque mover cajitas y flechas con el ratón es un rollo.

Hoy os quiero enseñar una herramienta que ha cambiado mi forma de hacerlos: el servidor MCP oficial de draw.io, publicado por JGraph (la empresa que hay detrás de draw.io) en github.com/jgraph/drawio-mcp. Con él le pides el diagrama a tu asistente de IA en lenguaje natural y te lo abre directamente en el editor de draw.io, listo para retocar a mano. Nada de imágenes generadas que no puedes editar: un diagrama de draw.io de verdad.

Cómo funciona el MCP de draw.io: Claude Code genera el diagrama, el servidor MCP lo empaqueta en una URL y draw.io lo abre en el navegador. Este diagrama, por cierto, está hecho así

Cómo funciona el MCP de draw.io: Claude Code genera el diagrama, el servidor MCP lo empaqueta en una URL y draw.io lo abre en el navegador. Este diagrama, por cierto, está hecho así

En el artículo veremos qué es exactamente, cómo instalarlo en Claude Code, Codex y OpenCode, qué herramientas expone, y lo pondremos a prueba con un ejemplo realista: una arquitectura desacoplada basada en eventos y microservicios. Por último os contaré cómo guardo los ficheros fuente .drawio en el repositorio junto al PNG, para que el diagrama no se convierta en una imagen huérfana que nadie sabe regenerar.


Qué es un MCP, en dos líneas

El Model Context Protocol (MCP) es un protocolo abierto que permite a un asistente de IA (Claude Code, Claude Desktop, Cursor, Copilot...) usar herramientas externas de forma estandarizada. Un servidor MCP expone una lista de tools con sus parámetros, y el modelo decide cuándo llamarlas. Es el "USB" de los asistentes: escribes el servidor una vez y funciona con cualquier cliente compatible.

En nuestro caso, el servidor de draw.io le da al modelo herramientas del tipo "abre este diagrama en draw.io" o "búscame el icono de AWS Lambda".


Por qué este MCP

El servidor se distribuye como paquete npm, @drawio/mcp, y se ejecuta en local con npx. Recibe el diagrama del modelo y lo abre en el editor de draw.io de tu navegador. Tiene dos ventajas que para mí son decisivas:

  • Abre el editor completo. No te quedas con una vista previa: tienes draw.io con todas sus paletas para corregir lo que el modelo no haya clavado.
  • El diagrama no se envía a los servidores de draw.io. Tiene matices importantes, así que le dedico una sección entera más abajo.

Instalación

Solo necesitáis Node.js, porque el servidor se lanza con npx. Es un servidor MCP estándar por stdio, así que funciona igual en cualquier cliente compatible; lo único que cambia es dónde se escribe la configuración. Os dejo la configuración para tres clientes: Claude Code, Codex y OpenCode.

Claude Code

Una línea:

claude mcp add drawio -- npx -y @drawio/mcp

Si queréis compartirlo con el resto del equipo, añadidlo con alcance de proyecto. Así se guarda en un .mcp.json en la raíz del repo, que se versiona como cualquier otro fichero:

claude mcp add --scope project drawio -- npx -y @drawio/mcp
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "@drawio/mcp"]
    }
  }
}

Con claude mcp list comprobáis que conecta, y dentro de Claude Code el comando /mcp os muestra el servidor y las herramientas que expone. En Claude Desktop el bloque mcpServers es el mismo, pero va en claude_desktop_config.json (en macOS, en ~/Library/Application Support/Claude/).

Codex

Codex (el agente de terminal de OpenAI) también tiene su comando:

codex mcp add drawio -- npx -y @drawio/mcp

Que no hace otra cosa que añadir esta sección a ~/.codex/config.toml, por si preferís escribirla a mano:

[mcp_servers.drawio]
command = "npx"
args = ["-y", "@drawio/mcp"]

Lo comprobáis con codex mcp list.

OpenCode

En OpenCode se declara bajo la clave mcp del opencode.json, en la raíz del proyecto o en ~/.config/opencode/opencode.json si lo queréis para todos los proyectos. Ojo, que aquí el comando y sus argumentos van juntos en un único array:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "drawio": {
      "type": "local",
      "command": ["npx", "-y", "@drawio/mcp"],
      "enabled": true
    }
  }
}

Lo comprobáis con opencode mcp list.

Dos variables de entorno útiles

DRAWIO_BROWSER=off. Por defecto, cada llamada abre el navegador en la máquina donde corre el servidor MCP. Si trabajáis por SSH o en un entorno remoto, el navegador se intentaría abrir en el sitio equivocado. Con esta variable el servidor se limita a devolver la URL, y la abrís vosotros donde queráis. Cada cliente la declara a su manera:

# Claude Code
claude mcp add drawio -e DRAWIO_BROWSER=off -- npx -y @drawio/mcp

# Codex
codex mcp add drawio --env DRAWIO_BROWSER=off -- npx -y @drawio/mcp

En los ficheros de configuración, es la clave env en el .mcp.json de Claude Code, una tabla [mcp_servers.drawio.env] en el config.toml de Codex, y la clave environment (no env) en el opencode.json:

"drawio": {
  "type": "local",
  "command": ["npx", "-y", "@drawio/mcp"],
  "enabled": true,
  "environment": { "DRAWIO_BROWSER": "off" }
}

DRAWIO_BASE_URL. Cambia el editor que se abre, que por defecto es https://app.diagrams.net/. Sirve para usar un draw.io autoalojado, y lo vemos en la sección de privacidad.


Las herramientas que expone

En el momento de escribir esto (versión 1.13.0 del paquete), el servidor ofrece estas tools:

ToolPara qué sirve
open_drawio_xmlAbre un diagrama en formato nativo de draw.io (XML mxGraph). La más potente: control total de estilos y posiciones
open_drawio_mermaidConvierte código Mermaid en un diagrama editable de draw.io
open_drawio_csvGenera el diagrama a partir de datos tabulares (organigramas, por ejemplo)
search_shapesBusca entre unas 10.000 formas (AWS, Azure, GCP, Kubernetes, Cisco, BPMN...) y devuelve el estilo exacto para usarlas
get_drawio_referenceDevuelve la guía completa de XML o de Mermaid, para que el modelo la lea antes de diagramas complejos
list_pages / get_page / set_pageLeen y modifican páginas concretas de un .drawio local de varias páginas

Las tres open_drawio_* aceptan además lightbox (vista de solo lectura) y dark ("auto", "true" o "false"). Y open_drawio_xml tiene dos opciones de maquetación muy interesantes:

  • postLayout: "elk": recoloca todos los nodos con el algoritmo de capas de ELK y traza las aristas. Ideal cuando no quieres pelearte con coordenadas.
  • routing: "libavoid": respeta tus posiciones pero reenruta las flechas para que esquiven las cajas.

Un detalle que me gustó al leer el código: antes de abrir nada, el servidor repara y normaliza el XML. Quita el texto que el modelo haya dejado alrededor (un bloque de código de Markdown, por ejemplo), escapa los < y & sueltos en atributos, recoloca las aristas en el contenedor correcto y agranda los contenedores que se quedarían cortos. Según el README, esos pequeños fallos rompían alrededor del 3 % de los diagramas escritos por un LLM. Es justo el tipo de pulido que separa una demo de una herramienta que puedes usar a diario.

¿XML o Mermaid?

Si ya usáis Mermaid, open_drawio_mermaid es la vía rápida: el modelo escribe muy bien Mermaid y draw.io lo convierte en formas editables. Para diagramas de secuencia, de clases o diagramas ER es perfecto.

Para diagramas de arquitectura prefiero el XML. Mermaid decide la maquetación por ti, y en cuanto quieres agrupar cosas en contenedores, alinear filas o dar un significado a cada color, se queda corto. Con XML el modelo coloca cada caja donde le dices.


Privacidad: qué sale de tu máquina y qué no

Si vais a dibujar la arquitectura de algo del trabajo, conviene tener claro por dónde viaja el diagrama, porque hay más piezas de las que parece.

Lo que se queda en local. @drawio/mcp es un proceso de Node que corre en tu máquina y habla con el asistente por stdio. No usa draw.io Desktop ni ningún servicio para generar el diagrama: repara el XML, aplica routing: "libavoid" si se lo pides, lo comprime y construye la URL. Todo eso ocurre en local.

El editor, en cambio, es la web de draw.io. La URL que genera apunta a https://app.diagrams.net/, así que el navegador descarga la aplicación de los servidores de draw.io. Pero el diagrama va en el fragmento de la URL (#R...), y el fragmento, lo que va detrás del #, nunca se envía al servidor en la petición HTTP: lo lee el JavaScript de draw.io ya en tu navegador. Es decir, se descarga la aplicación, pero tu diagrama no sale hacia draw.io.

Ahora bien, hay tres excepciones a tener en cuenta:

  • postLayout: "elk" descarga, la primera vez que se usa, el paquete de maquetación ELK desde el CDN de draw.io (luego queda en caché). Lo que se descarga es código, no tu diagrama, pero es una conexión saliente.
  • search_shapes busca primero en las bibliotecas de formas que vienen dentro del paquete. Si no encuentra nada bueno, completa los resultados consultando el servicio de iconos de draw.io, y en ese caso la consulta (por ejemplo kafka) sí sale de tu máquina. Además, esos iconos no se incrustan en el diagrama: son imágenes enlazadas. El logo de Kafka del ejemplo está en icons.diagrams.net, y cualquiera que abra el .drawio, o lo exporte a PNG, necesita conexión para verlo.
  • La URL lleva el diagrama dentro. No viaja al servidor, pero se queda en el historial del navegador, y si la pegáis en un chat o en un ticket estáis compartiendo el diagrama completo. Tratadla como el propio fichero.

Y lo más obvio, que a veces se olvida: el XML del diagrama lo escribe el modelo. Todo lo que describís en el prompt y todo el contenido del diagrama pasa por el proveedor del LLM que uséis (Anthropic, OpenAI...), igual que el código que le enseñáis. El MCP de draw.io no añade ni quita nada a eso: si un diagrama no puede salir de la empresa, la frontera está en el asistente, no en draw.io.

Todo en local con draw.io autoalojado

Si queréis que ni siquiera la aplicación del editor venga de fuera, draw.io tiene imagen Docker oficial. La levantáis y apuntáis el MCP a ella con DRAWIO_BASE_URL:

docker run -d --name drawio -p 8080:8080 jgraph/drawio

claude mcp add drawio -e DRAWIO_BASE_URL=http://localhost:8080/ -- npx -y @drawio/mcp

En Codex sería --env DRAWIO_BASE_URL=... y en OpenCode, la clave environment, como vimos en la instalación. Con esto el editor se sirve desde vuestra máquina. Eso sí, ELK y la parte de iconos de search_shapes siguen tirando de los servidores de draw.io, así que si queréis cero conexiones salientes, evitadlos y usad formas básicas.


Ejemplo: arquitectura desacoplada basada en eventos

Vamos al grano. Quería un diagrama de algo que aparece en casi cualquier sistema mediano: una arquitectura de microservicios que se comunican mediante eventos a través de un broker, en lugar de llamarse unos a otros por HTTP. El típico flujo de pedidos de una tienda online.

El prompt fue más o menos este:

Usa open_drawio_xml para dibujar una arquitectura desacoplada basada en eventos
para el flujo de pedidos de un e-commerce:

- Arriba: clientes (web Angular y app React Native) -> API Gateway -> Order Service
  con su PostgreSQL. A la derecha, un Schema Registry.
- En el centro, ocupando todo el ancho, el broker Kafka con los topics orders,
  payments, inventory, shipping y una DLQ.
- Abajo, los consumidores: Payment, Inventory, Shipping y Notification, cada uno
  con su propia base de datos (Notification habla con un proveedor de email/push).
- Flechas naranjas continuas = publica evento (rotuladas con el evento),
  naranjas discontinuas = consume, grises = llamadas síncronas. Añade una leyenda.
- Order Service consume payments e inventory para actualizar el estado del pedido.
- Pon el logo de Kafka en la cabecera del broker (búscalo con search_shapes).
- Usa routing "libavoid" para que las flechas esquiven las cajas.

Fijaos en que el prompt no dice nada de coordenadas, pero sí describe la disposición por filas y, sobre todo, qué significa cada estilo de flecha. Es lo que más mejora el resultado: si no le das una semántica visual, el modelo pinta todas las flechas iguales y el diagrama no se entiende.

Con esto, Claude Code hizo dos llamadas al MCP: primero search_shapes con la consulta kafka, que devolvió el estilo del logo (una imagen de icons.diagrams.net), y después open_drawio_xml con el XML del diagrama y routing: "libavoid". Como tengo DRAWIO_BROWSER=off, la respuesta fue simplemente la URL https://app.diagrams.net/...#R..., que abrí en mi navegador.

Este es el resultado final, tras una segunda iteración de la que os hablo más abajo:

Arquitectura desacoplada basada en eventos: los microservicios no se llaman entre sí, publican y consumen eventos en Kafka, y cada uno es dueño de su base de datos

Arquitectura desacoplada basada en eventos: los microservicios no se llaman entre sí, publican y consumen eventos en Kafka, y cada uno es dueño de su base de datos

Podéis descargar el fuente .drawio y abrirlo en app.diagrams.net para trastear con él.

Cómo leer el diagrama

Ya que estamos, merece la pena repasar qué cuenta el diagrama, porque es un patrón que conviene conocer:

  1. El cliente hace un POST /orders a través del API Gateway. Es la única llamada síncrona de todo el flujo: el Order Service guarda el pedido en su base de datos y responde inmediatamente con un "pedido recibido".
  2. El Order Service publica OrderCreated en el topic orders. Y aquí acaba su trabajo: no sabe quién va a escuchar ese evento, ni le importa.
  3. Payment e Inventory están suscritos a orders y reaccionan en paralelo: uno cobra y el otro reserva stock. Cada uno publica su resultado (PaymentCompleted, StockReserved) en su propio topic.
  4. Shipping escucha payments: cuando hay pago, prepara el envío y publica ShipmentDispatched, que a su vez escucha Notification para avisar al cliente.
  5. El Order Service cierra el círculo consumiendo payments e inventory para actualizar el estado del pedido.

Las ventajas de este diseño se ven en el propio dibujo:

  • Desacoplamiento. Ningún servicio conoce a los demás, solo los eventos. Si mañana quiero añadir un servicio de analítica o de fidelización, lo suscribo a orders y no toco ni una línea del Order Service.
  • Resiliencia. Si el servicio de notificaciones se cae, los pedidos se siguen creando y cobrando. Los eventos esperan en Kafka y se procesan cuando vuelve.
  • Cada servicio es dueño de sus datos (database per service). Por eso cada uno tiene su propia base de datos, incluso de tecnologías distintas (MongoDB para el stock, por ejemplo). Nadie lee la base de datos de otro.
  • El Schema Registry guarda los contratos de los eventos (en Avro, por ejemplo) y evita que un productor publique un evento que rompa a sus consumidores. En una arquitectura así, los eventos son la API, y hay que versionarlos con el mismo cuidado.
  • La DLQ (dead letter queue) recoge los eventos que un consumidor no ha podido procesar tras agotar los reintentos, para que no bloqueen la cola y puedan revisarse a mano.

No todo son ventajas. Con eventos se pasa a tener consistencia eventual: durante unos segundos el pedido existe pero aún no está cobrado. Además, depurar un flujo repartido entre cinco servicios es bastante más difícil que seguir una llamada HTTP, así que necesitas trazas distribuidas (OpenTelemetry) desde el primer día. Y en un sistema real, el Order Service no debería guardar en base de datos y publicar en Kafka por separado: si falla entre medias, el pedido se queda sin evento. Para eso está el patrón Transactional Outbox, que he dejado fuera del diagrama para no complicarlo.

La primera versión no fue la buena

Como casi siempre que trabajas con un LLM, no salió a la primera. El diagrama tenía la estructura correcta, todas las cajas en su sitio y los colores bien, pero el enrutado automático de libavoid reutilizaba tramos de flechas:

Primera versión que devolvió el MCP: la estructura es correcta, pero `OrderCreated` sale por el mismo punto del Order Service por el que entran las suscripciones, y `ShipmentDispatched` se superpone a la suscripción de Shipping

Primera versión que devolvió el MCP: la estructura es correcta, pero OrderCreated sale por el mismo punto del Order Service por el que entran las suscripciones, y ShipmentDispatched se superpone a la suscripción de Shipping

Fijaos en el Order Service: OrderCreated sale por el mismo punto por el que entran las dos suscripciones de actualiza estado, de forma que no se sabe qué flecha va hacia dónde. Y abajo a la derecha, la flecha de ShipmentDispatched se monta encima de la suscripción de Shipping al topic payments.

El motivo es que, sin anclajes, libavoid conecta cada flecha por donde le resulta más corto, sin tener en cuenta que otra flecha ya esté usando ese mismo punto de la caja. Así que la segunda petición fue:

Varias flechas comparten tramo: OrderCreated y las suscripciones del Order Service
salen y entran por el mismo punto, y ShipmentDispatched pisa la suscripción de
Shipping. Fija los puntos de anclaje (exitX/entryX) para que cada flecha tenga su
propia salida y entrada, y vuelve a abrirlo con libavoid.

Con los anclajes fijados (por ejemplo, las publicaciones salen por el 75 % del borde superior de cada servicio y las suscripciones entran por el 25 %), libavoid ya traza cada flecha por su carril, como veis en el diagrama final.

Esto mismo se podía haber arreglado a mano en el editor arrastrando los extremos de las flechas. Mi regla es pedírselo al modelo cuando el cambio afecta a varios elementos o tiene "lógica" ("todas las publicaciones salen por arriba a la derecha"), y hacerlo a mano cuando es mover una caja 20 píxeles.

Para que os hagáis una idea del formato, así es una caja y una flecha de publicación en el XML:

<mxCell id="order" value="&lt;b&gt;Order Service&lt;/b&gt;&lt;br&gt;crea pedidos"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
        vertex="1" parent="1">
  <mxGeometry x="540" y="100" width="160" height="70" as="geometry"/>
</mxCell>

<mxCell id="p_order" value="OrderCreated"
        style="edgeStyle=orthogonalEdgeStyle;rounded=1;html=1;strokeColor=#d79b00;strokeWidth=2;"
        edge="1" source="order" target="t_orders" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Es verboso, pero muy regular, y los LLM lo escriben con soltura. Además es texto plano, con lo que los cambios se ven en un git diff. Y eso nos lleva al último punto.

¿Y cómo paso de la URL a un fichero? Desde el editor, con Archivo → Guardar como eligiendo "Dispositivo", que descarga el .drawio. Otra opción es pedírselo al propio Claude Code: el diagrama va dentro de la URL, detrás de #R, como XML comprimido con deflate y codificado en base64. Unas pocas líneas de Node con zlib.inflateRawSync lo devuelven a XML. Es lo que hice yo, para que el fichero del repositorio sea exactamente lo que generó el MCP.


Fuentes en el repo, imágenes en el artículo

Un diagrama exportado como PNG es un callejón sin salida: dentro de seis meses quieres añadir un servicio y te toca redibujarlo entero. Por eso en este blog he adoptado una convención sencilla: el .drawio es el código fuente y el PNG es un artefacto generado. Los dos van al repositorio, uno al lado del otro:

src/posts/drawio-mcp/
├── index.md
├── diagrams/
│   ├── arquitectura-eventos.drawio        ← fuente (XML, editable, diffable)
│   └── como-funciona-drawio-mcp.drawio
└── images/
    ├── arquitectura-eventos.png           ← lo que se embebe en el artículo
    └── como-funciona-drawio-mcp.png

En el Markdown se embebe el PNG, como cualquier otra imagen:

![Arquitectura desacoplada basada en eventos](images/arquitectura-eventos.png)

Como el build del blog copia todos los ficheros de la carpeta del post a /static/posts/<slug>/, el .drawio queda además publicado y se puede enlazar para descargarlo, como habéis visto más arriba.

Exportar sin instalar nada

Para pasar de .drawio a PNG no hace falta tener draw.io instalado: draw.io Desktop tiene un modo de línea de comandos, y hay una imagen Docker, rlespinasse/drawio-desktop-headless, que lo ejecuta sin pantalla:

docker run --rm --shm-size=1g -w /data -v "$PWD":/data \
  rlespinasse/drawio-desktop-headless \
  -x -f png -s 2 -b 24 \
  -o src/posts/drawio-mcp/images/arquitectura-eventos.png \
  src/posts/drawio-mcp/diagrams/arquitectura-eventos.drawio
  • -x -f png: exportar a PNG.
  • -s 2: escala ×2, para que se vea nítido en pantallas de alta densidad.
  • -b 24: 24 px de margen alrededor.
  • --shm-size=1g: sin esto, el proceso de renderizado de Electron se me caía con un escueto "Renderer process crashed". La memoria compartida que Docker da por defecto (64 MB) se le queda corta.

Para no tener que acordarme, lo he metido en un script, docker/drawio-export.sh, con su objetivo en el Makefile. Recorre todos los src/posts/*/diagrams/*.drawio y deja cada PNG en la carpeta images/ del mismo post:

make diagrams

El script copia los ficheros con docker cp en lugar de montar un volumen, así funciona también cuando el daemon de Docker es remoto y no ve tu sistema de ficheros.

Alternativa: .drawio.png. draw.io puede incrustar el XML del diagrama dentro del propio PNG (opción --embed-diagram en la CLI, o "Include a copy of my diagram" al exportar desde el editor). El resultado es una imagen normal que, abierta en draw.io, vuelve a ser editable. Es cómodo porque es un único fichero, pero yo prefiero tener el XML aparte: se lee y se compara en un git diff, mientras que un PNG es un binario opaco.


Consejos para sacarle partido

  • Nombra la herramienta en el prompt ("usa opendrawioxml..."). Si no, el modelo puede decidir contestarte con un bloque de Mermaid en el chat o con un SVG hecho a mano. El propio README lo recomienda.
  • Describe la semántica visual: qué significa cada color, cada estilo de línea, y pide una leyenda. Es lo que más mejora el resultado.
  • Describe la disposición por filas o columnas ("arriba los clientes, en el centro el broker..."). En diagramas de arquitectura suele dar mejor resultado que postLayout: "elk", que brilla en flujos pero coloca los nodos por capas según las flechas, no según cómo quieras agruparlos tú.
  • Para iconos de proveedores cloud, pide que use search_shapes antes. Así usa los estilos reales de AWS o Kubernetes en lugar de cajas genéricas con el nombre dentro.
  • Itera sobre el fichero, no sobre la URL. Una vez que tienes un .drawio en el repo, pídele los cambios sobre ese fichero. Las herramientas get_page/set_page le permiten editar una página concreta de un .drawio local sin cargarlo entero.
  • Revisa siempre. El modelo dibuja exactamente lo que le describes, incluidos tus errores de concepto. Un diagrama de arquitectura que parece profesional pero está mal es peor que no tener diagrama.

Cierre

Lo que más me gusta de este MCP es que no intenta sustituir a draw.io, sino ahorrarte el folio en blanco. La IA hace el 80 % aburrido (crear cajas, alinearlas, conectar flechas, ponerles estilos coherentes) y tú dedicas tu tiempo al 20 % que importa: que el diagrama cuente lo que tiene que contar.

Y con los fuentes .drawio versionados junto al código, el diagrama deja de ser una foto fija y pasa a ser algo vivo que se actualiza con el sistema. Que es, al final, lo que siempre nos decimos que vamos a hacer con la documentación y nunca hacemos.

Tenéis toda la información en el repositorio oficial: github.com/jgraph/drawio-mcp. ¡Nos vamos leyendo!