mcp-mermaid MCP — Casos de uso, Instalar & Demo en vivo

Name: mcp-mermaid MCP Server
Author: hustcc

Por qué usarlo

Características clave

Soporte completo de sintaxis Mermaid — diagramas de flujo, secuencia, clases, estados, ER, gantt, etc.
Seis formatos de salida: base64, texto SVG, código fuente Mermaid, archivo PNG, URL SVG, URL PNG
Validación de sintaxis incorporada y autocorrección iterativa
backgroundColor y tema configurables
Despliegue Docker + transportes HTTP SSE/Streamable

Demo en vivo

Cómo se ve en la práctica

mermaid.replay ▶ listo

0/0

Instalar

Elige tu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ],
      "_inferred": true
    }
  }
}

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mermaid",
      "command": "npx",
      "args": [
        "-y",
        "mcp-mermaid"
      ]
    }
  ]
}

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

{
  "context_servers": {
    "mermaid": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-mermaid"
        ]
      }
    }
  }
}

Añádelo a context_servers. Zed recarga en caliente al guardar.

claude mcp add mermaid -- npx -y mcp-mermaid

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: mcp-mermaid

Genera un diagrama de arquitectura de sistemas a partir de descripción

👤 Ingenieros que escriben documentos de diseño ⏱ ~10 min beginner

Cuándo usarlo: Has descrito una arquitectura en un documento y quieres un diagrama sin salir del chat.

Requisitos previos

mcp-mermaid instalado — npx -y mcp-mermaid en tu configuración del cliente MCP

Flujo

Describe el sistema

Aquí está mi arquitectura: Cloudflare → API (Node) → Postgres + Redis → Worker (Go). Genera un diagrama de flujo Mermaid que muestre esto.✓ Copiado

→ Código Mermaid válido renderizado como SVG
Itera sobre el estilo

Haz Cloudflare azul, Postgres verde, Redis rojo. Usa bordes punteados para operaciones asincrónicas.✓ Copiado

→ Diagrama revisado
Guarda en archivo

Genera como archivo PNG en ./docs/arch.png con fondo blanco.✓ Copiado

→ Archivo en disco

Resultado: Un PNG de arquitectura que puedes incluir en el documento de diseño.

Errores comunes

Los diagramas muy complejos alcanzan los límites de diseño de Mermaid — Divide en varios diagramas o usa agrupación de subgráfos
Los colores del tema no coinciden con tu documento — Pasa la configuración del tema de forma explícita en lugar de confiar en los valores predeterminados

Combinar con: filesystem

Crea un diagrama de secuencia en un reporte de errores

👤 Ingenieros que reportan errores de condiciones de carrera ⏱ ~5 min beginner

Cuándo usarlo: La descripción en prosa de quién llama a quién cuándo es difícil de leer.

Flujo

Describe la secuencia

El cliente envía POST, la API inicia una transacción, escribe en la BD, y se bloquea antes de confirmar. Mientras tanto, llega un reintento del cliente. Dibuja un diagrama de secuencia.✓ Copiado

→ Secuencia clara con líneas de vida paralelas
Inserta en el problema

Dame el código fuente Mermaid para que pueda pegarlo en un problema de GitHub (que renderiza Mermaid de forma nativa).✓ Copiado

→ Código fuente listo para pegar

Resultado: Un reporte de errores que los revisores pueden entender en 10 segundos.

Combinar con: github

Genera un Gantt de proyecto a partir de una línea de tiempo

👤 Líderes de proyecto que no quieren pagar por software gantt para un uso puntual ⏱ ~5 min beginner

Cuándo usarlo: Línea de tiempo ad-hoc para un PRD o lanzamiento.

Flujo

Lista las fases

Fases: Descubrimiento (2 semanas), Diseño (3 semanas), Implementación (6 semanas), QA (2 semanas solapadas con las últimas 2 semanas de implementación). Comienza 2026-05-01. Crea un gantt.✓ Copiado

→ Código Gantt válido
Genera PNG

Guarda como PNG y también dame la URL que puedo incrustar en el PRD.✓ Copiado

→ Ruta PNG + URL alojada

Resultado: Un gráfico de línea de tiempo para tu PRD en menos de un minuto.

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

mermaid + filesystem

Guarda diagramas generados como recursos versionados

Genera diagrama de arquitectura v2 como ./docs/arch-v2.png y actualiza la referencia en ./docs/README.md.✓ Copiado

mermaid + github

Coloca el código fuente Mermaid en la descripción del PR — GitHub lo renderiza de forma nativa

Redacta una descripción del PR explicando el cambio en el flujo de datos, incluye un diagrama de secuencia Mermaid en línea.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
generate_mermaid	source: str (DSL Mermaid), output: base64\|svg\|mermaid\|file\|svgUrl\|pngUrl, theme?, backgroundColor?	Cualquier generación de diagrama	gratuito (renderizado local) o 1 llamada API para URLs alojadas
validate_mermaid	source: str	Antes de generar si no estás seguro sobre la sintaxis	gratuito

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: El renderizado local es gratuito; la salida de URL alojada usa mermaid.ink que es gratuito con uso razonable
Tokens por llamada: Pequeño — el DSL del diagrama es compacto
Monetario: Gratuito
Consejo: Prefiere la salida 'mermaid' para GitHub/documentos que renderizan de forma nativa; solo usa PNG/SVG cuando sea necesario renderizar del lado del servidor.

Seguridad

Permisos, secretos, alcance

Almacenamiento de credenciales: Ninguno

Salida de datos: Renderizado local para base64/svg; mermaid.ink para URLs alojadas

Las URLs alojadas (mermaid.ink) exponen el contenido de tu diagrama — no las uses para diagramas de sistemas confidenciales.
El renderizado de PNG crea un navegador sin interfaz — asegúrate de que no esté expuesto en internet público.

Resolución de problemas

Errores comunes y soluciones

Error de análisis Mermaid

El LLM emitió DSL inválido. Valida primero vía validate_mermaid; mcp-mermaid también se autocorrige en el segundo intento.

Verificar: validate_mermaid en el código fuente

La salida PNG falla en Docker

La imagen necesita un navegador sin interfaz; usa la imagen oficial de Docker que lo incluye.

Verificar: docker run hustcc/mcp-mermaid

Diagrama demasiado grande, se corta

Divide en subgráfos o divide en varios diagramas.

Alternativas

mcp-mermaid vs otros

Alternativa	Cuándo usarla	Contrapartida
PlantUML MCP	Prefieres la superficie UML más profunda de PlantUML	Requiere Java runtime
antv-chart / mcp-server-chart	Necesitas gráficos de datos más que diagramas	Forma diferente de salida
Mermaid puro a través del editor web	No estás en un flujo de chat	Sin integración MCP

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills