Diagrams.so

Generar y editar diagramas de arquitectura en la nube como archivos nativos de draw.io, a partir de un prompt o desde Terraform

GitHubPrueba este MCPPatrocinado

Documentación

@diagrams-so/mcp

El servidor MCP de Diagrams.so — genera, edita y gestiona diagramas de arquitectura en la nube desde cualquier cliente MCP (Claude Desktop, Claude Code, Cursor). Es un cliente stdio ligero sobre la API pública de Diagrams.so (/api/v2); cada herramienta es una llamada REST.

Inicio rápido

Requiere Node ≥ 18. No hay clave API que copiar: te conectas aprobando en un navegador.

# 1. add the server to Claude Code
claude mcp add diagrams-so -- npx -y @diagrams-so/mcp

# 2. connect this machine (a browser opens, press Approve)
npx @diagrams-so/mcp login

Reinicia tu cliente y luego pregunta: "Genera un diagrama de aplicación web de 3 niveles en AWS y muéstrame las advertencias." Ejecuta /mcp si quieres confirmar primero que las 23 herramientas estén registradas.

¿Lo usas mucho? Instálalo una vez y el comando se acorta:

npm i -g @diagrams-so/mcp
diagrams-so login

El servidor habla con producción (https://api.diagrams.so/api/v2) por defecto. Apúntalo a una API local o autoalojada con DIAGRAMS_API_BASE.

¿Usas Claude Desktop o Cursor en lugar de la CLI? Consulta Añádelo a tu cliente MCP. ¿Prefieres una instalación de un clic, sin terminal? Consulta Instalación en un clic (MCPB).

Sin terminal en absoluto (Claude Desktop)

Añade el servidor a la configuración de tu cliente (abajo) y luego solo pide un diagrama. Como la máquina aún no está conectada, la primera llamada a la herramienta responde con un enlace. Ábrelo, pulsa Aprobar y vuelve a preguntar. No hay nada que instalar ni escribir.

Generar un diagrama desde Claude

login solo conecta la máquina. Nunca genera nada por sí mismo, así que no hay ningún comando generate que escribir en una terminal. Escribes el prompt en el cuadro de chat normal de tu asistente y él llama a las herramientas por ti.

Cliente	Dónde escribes el prompt
Claude Code	el chat de terminal, el mismo lugar donde preguntas cualquier otra cosa
Claude Desktop	la caja de mensajes normal
Cursor	el panel de chat o compositor

Los servidores MCP se cargan al inicio, así que reinicia tu cliente después de añadirlo. Luego ejecuta /mcp y confirma que diagrams-so muestra 23 herramientas.

Ahora solo pregunta, en inglés sencillo:

Genera una aplicación web de tres niveles en AWS con un ALB, Auto Scaling de EC2 y RDS Multi-AZ. Muéstrame las advertencias de diseño y luego expórtala como draw.io.

Detrás de esa única frase, el asistente llama a generate_diagram, luego a get_warnings y luego a export_diagram. Nunca nombras una herramienta ni escribes JSON.

Más cosas que vale la pena preguntar, una vez que tienes un diagrama:

Las advertencias mencionan que no hay cifrado en tránsito. Arregla eso y muéstrame la nueva puntuación.

Añade una distribución de CloudFront delante del ALB.

Re-expórtalo como SVG para poder ponerlo en el README.

Cada respuesta incluye el coste en créditos y tu saldo restante. Generar, editar, corregir y reorganizar el diseño gastan créditos; leer, advertencias y cada exportación son gratuitos.

El archivo .drawio que guarda el asistente se abre en app.diagrams.net o en la aplicación de escritorio, totalmente editable: es XML real de draw.io, no una imagen.

¿Prefieres no usar ningún asistente? diagrams.so/create tiene lo mismo como página web: escribe el prompt en el cuadro. Sin instalación, sin login, sin MCP.

Herramientas (23)

Crear y cambiar (mutaciones)

Herramienta	Qué hace	Coste
`generate_diagram`	Crear un diagrama a partir de un prompt → id + XML de draw.io + advertencias + puntuación	créditos
`edit_diagram`	Aplicar un cambio en lenguaje natural (nueva versión)	créditos
`fix_warning`	Resolver una advertencia de Well-Architected	créditos
`relayout_diagram`	Reorganizar el diseño con IA (asíncrono; los primeros 2/diagrama gratis, luego confirmar)	créditos*
`import_diagram`	Importar XML existente de draw.io como nuevo diagrama	gratis
`update_diagram`	Renombrar / cambiar visibilidad / reemplazar XML	gratis
`revert_diagram`	Revertir a una versión anterior	gratis
`delete_diagram`	Eliminación suave de un diagrama (destructivo)	gratis
`fork_template`	Copiar un diagrama público/de biblioteca a tu cuenta (privado)	gratis

Leer (gratis)

Herramienta	Qué hace
`get_diagram`	Obtener el XML + puntuación de un diagrama
`list_diagrams`	Listar tus diagramas (paginado por cursor)
`get_warnings`	Hallazgos de Well-Architected para un diagrama
`export_diagram`	Archivo `drawio` o `svg` sin procesar (gratis en todos los planes; el SVG del plan gratuito tiene marca de agua)
`list_versions`	Historial de versiones (con `is_current`)
`get_version`	XML + puntuación de una versión específica
`get_relayout_status`	Consultar un trabajo de reorganización asíncrono
`search_gallery`	Buscar diagramas de la comunidad pública + biblioteca curada
`enhance_prompt`	Convertir una idea aproximada en un prompt detallado
`clarify_prompt`	Obtener preguntas aclaratorias para un prompt vago
`get_usage`	Plan + créditos + estimaciones de coste
`get_usage_history`	Libro mayor de créditos detallado por tarea (acción, créditos, diagrama, superficie) con filtros + un recuento de sesión en vivo
`whoami`	Cuenta, plan, ámbitos, modo en vivo/prueba
`list_capabilities`	Tipos de diagrama / proveedores / formatos de exportación válidos

Las lecturas y exportaciones son gratuitas; generate / edit / fix / relayout cuestan créditos, y delete es destructivo. relayout pide confirm=true antes de cobrar.

CLI

Comandos

Instalar el paquete pone diagrams-so en tu PATH. El nombre más largo diagrams-so-mcp sigue funcionando, y npx @diagrams-so/mcp <command> funciona sin instalar nada.

npm i -g @diagrams-so/mcp

diagrams-so login          # connect this machine (a browser opens, press Approve)
diagrams-so whoami         # which account is this machine connected as
diagrams-so logout         # remove the local credential
diagrams-so install        # print client config to paste

Entorno

Var	Requerido	Predeterminado
`DIAGRAMS_API_KEY`	❌	— (solo para CI y headless; `login` es la ruta normal)
`DIAGRAMS_API_BASE`	❌	`https://api.diagrams.so/api/v2` (producción; anular para local/autoalojado)
`DIAGRAMS_API_TIMEOUT_MS`	❌	`450000` (red de seguridad por solicitud; se sitúa por encima de la escalera de tiempos de espera completa del lado del servidor de la API)
`DIAGRAMS_BROWSER`	❌	— (`login` abre tu navegador predeterminado; establece por ejemplo `Google Chrome` cuando tu sesión de Diagrams.so vive en un navegador no predeterminado)
`DIAGRAMS_NO_BROWSER`	❌	— (establece cualquier valor para evitar que `login` abra un navegador; la URL siempre se imprime)
`DIAGRAMS_NO_AUTO_LOGIN`	❌	— (establece cualquier valor para deshabilitar la conexión dentro de la herramienta; las herramientas no autenticadas entonces solo dicen que ejecutes `login`)

Añádelo a tu cliente MCP

El paquete publicado se ejecuta directamente desde npm, así que no hay ruta que completar ni clave en la configuración. Ejecuta npx @diagrams-so/mcp install para imprimir estos bloques para tu cliente.

Claude Code (CLI)

claude mcp add diagrams-so -- npx -y @diagrams-so/mcp
npx @diagrams-so/mcp login

Claude Desktop / Cursor (`claude_desktop_config.json` / `mcp.json`)

{
  "mcpServers": {
    "diagrams-so": {
      "command": "npx",
      "args": ["-y", "@diagrams-so/mcp"]
      // optional: "env": { "DIAGRAMS_API_BASE": "http://localhost:8000/api/v2" } for a local API
    }
  }
}

Conéctate ejecutando npx @diagrams-so/mcp login una vez, o pidiendo un diagrama y haciendo clic en el enlace que te da la primera llamada a la herramienta. Establece DIAGRAMS_API_KEY solo para máquinas CI y headless, donde no se puede abrir un navegador.

Reinicia el cliente y luego pregunta: "Genera un diagrama de aplicación web de 3 niveles en AWS y muéstrame las advertencias."

Instalación en un clic (MCPB)

Descarga diagrams-so.mcpb desde la última versión y arrástralo a Claude Desktop. Sin terminal, y ya no pide clave API: instálalo y luego conéctate en el primer uso haciendo clic en el enlace que te da la primera llamada a la herramienta.

Compilar el paquete tú mismo es un paso de colaborador, consulta Desarrollo local.

Smithery

El servidor está listado en smithery.ai/servers/diagrams-so/mcp, que lo instala por ti y lista las 23 herramientas con sus parámetros:

npx -y smithery mcp add diagrams-so/mcp

Mismo paquete, mismo paso login. Es el paquete MCPB que instala Smithery, no el paquete npm, así que la versión que se muestra allí sigue los lanzamientos en lugar de npm dist-tags.

Verifica que funciona

DIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs

Ejecuta el flujo completo (conectar → listar herramientas → whoami → generar → advertencias → corregir → exportar → manejo de errores).

Integración continua y lanzamientos

Flujo de trabajo	Disparador	Qué hace
CI (`ci.yml`)	cada push / PR	`npm ci` + `npm run build` en Node 18/20/22, luego una prueba de humo gratuita (`scripts/ci-smoke.mjs`) que lanza el servidor compilado y verifica que las 23 herramientas se registren. Sin llamadas a la API, sin créditos.
Prueba de humo en vivo (`live-smoke.yml`)	nocturno + manual	el flujo completo de extremo a extremo (`test-smoke.mjs`) contra la API real. Gasta créditos — se ejecuta solo cuando el secreto `DIAGRAMS_API_KEY` está configurado.
Lanzamiento (`release.yml`)	tag `vX.Y.Z`	compilar → `npm prune --omit=dev` → empaquetar `diagrams-so.mcpb` → adjuntar a un lanzamiento de GitHub. También publica en npm si un secreto `NPM_TOKEN` está configurado.

Haz un lanzamiento:

# bump "version" in package.json + manifest.json to match, commit, then:
git tag v1.2.0 && git push origin v1.2.0

La etiqueta debe coincidir con version de package.json (el flujo de trabajo lo impone). El paquete .mcpb aparece en el lanzamiento de GitHub; workflow_dispatch manual lo produce como artefacto descargable sin publicar (útil para probar un paquete).

Secretos/variables del repositorio (opcional): DIAGRAMS_API_KEY (prueba de humo en vivo), NPM_TOKEN (publicación en npm), variable DIAGRAMS_API_BASE (objetivo de prueba de humo en vivo no productivo).

Notas

stdout es el canal MCP — el servidor solo registra en stderr.
Los errores vuelven como errores limpios de herramienta MCP que llevan el code de la API, el estado HTTP y request_id.
El servidor nunca habla con servicios internos ni con la base de datos — solo con el /api/v2 público.
Las herramientas de larga duración siguen vivas más allá de los tiempos de espera del cliente. generate / edit / fix / relayout / enhance_prompt / clarify_prompt emiten un notifications/progress cada 10s mientras se ejecutan, para que los clientes MCP que restablecen su tiempo de espera de solicitud en el progreso (resetTimeoutOnProgress) no aborten una generación lenta en el valor predeterminado de 60s del SDK. Si tu cliente no restablece en el progreso, aumenta su tiempo de espera por llamada para estas herramientas.

Desarrollo local

Solo es necesario si estás cambiando el servidor en sí. Los usuarios deben instalar desde npm, consulta Inicio rápido.

git clone https://github.com/RedHold/diagrams-mcp-app-core.git
cd diagrams-mcp-app-core
npm install                  # installs deps and builds dist/ via the prepare hook
node scripts/ci-smoke.mjs    # all 23 tools register; no API calls, no credits

# point a client at your working copy
claude mcp add diagrams-so-dev -- node "$(pwd)/dist/index.js"

# build the MCPB bundle
npm run build && npx @anthropic-ai/mcpb pack