Mermaid MCP Server

Convierte diagramas Mermaid a imágenes PNG o SVG.

Documentación

Servidor MCP de Mermaid

Un servidor de Model Context Protocol (MCP) que convierte diagramas de Mermaid en imágenes PNG o archivos SVG. Este servidor permite a los asistentes de IA y otras aplicaciones generar diagramas visuales a partir de descripciones textuales utilizando la sintaxis de markdown de Mermaid.

Características

Convierte código de diagramas de Mermaid en imágenes PNG o archivos SVG
Soporta múltiples temas de diagramas (default, forest, dark, neutral)
Colores de fondo personalizables
Utiliza Puppeteer para renderizado de alta calidad en navegador sin interfaz gráfica
Implementa el protocolo MCP para una integración perfecta con asistentes de IA
Opciones de salida flexibles: devolver imágenes/SVG directamente o guardarlas en disco
Manejo de errores con mensajes de error detallados

Cómo Funciona

El servidor utiliza Puppeteer para lanzar un navegador sin interfaz gráfica, renderizar el diagrama de Mermaid a SVG y, opcionalmente, capturar una captura de pantalla del diagrama renderizado. El proceso implica:

Lanzar una instancia de navegador sin interfaz gráfica
Crear una plantilla HTML con el código de Mermaid
Cargar la biblioteca Mermaid.js
Renderizar el diagrama a SVG
Guardar el SVG directamente o tomar una captura de pantalla como PNG
Devolver la imagen/SVG directamente o guardarla en disco

Compilación

npx tsc

Uso

Uso con Claude desktop

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "@peng-shawn/mermaid-mcp-server"]
    }
  }
}

Uso con Cursor y Cline

env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server

Puedes encontrar una lista de diagramas de mermaid en ./diagrams, creados con el agente de Cursor usando el prompt: "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work"

Ejecutar con inspector

Ejecuta el servidor con inspector para pruebas y depuración:

npx @modelcontextprotocol/inspector node dist/index.js

El servidor se iniciará y escuchará en stdio los mensajes del protocolo MCP.

Aprende más sobre inspector aquí.

Instalación mediante Smithery

Para instalar Mermaid Diagram Generator para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Entornos Docker y Smithery

Cuando se ejecuta en contenedores Docker (incluido mediante Smithery), es posible que necesites gestionar las dependencias de Chrome:

El servidor ahora intenta usar el navegador incluido de Puppeteer por defecto
Si encuentras errores relacionados con el navegador, tienes dos opciones:

Opción 1: Durante la compilación de la imagen Docker:
- Establece PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true al instalar Puppeteer
- Instala Chrome/Chromium en tu contenedor Docker
- Establece PUPPETEER_EXECUTABLE_PATH en tiempo de ejecución para apuntar a la instalación de Chrome
Opción 2: Usar el Chrome incluido de Puppeteer:
- Asegúrate de que tu contenedor Docker tenga las dependencias necesarias para Chrome
- No es necesario establecer PUPPETEER_SKIP_CHROMIUM_DOWNLOAD
- El código usará el navegador incluido automáticamente

Para usuarios de Smithery, la última versión debería funcionar sin configuración adicional.

API

El servidor expone una única herramienta:

generate: Convierte código de diagrama de Mermaid en una imagen PNG o archivo SVG
- Parámetros:
  - code: El código del diagrama de Mermaid a renderizar
  - theme: (opcional) Tema para el diagrama. Opciones: "default", "forest", "dark", "neutral"
  - backgroundColor: (opcional) Color de fondo para el diagrama, p. ej. 'white', 'transparent', '#F0F0F0'
  - outputFormat: (opcional) Formato de salida para el diagrama. Opciones: "png", "svg" (por defecto "png")
  - name: Nombre para el archivo generado (requerido cuando CONTENT_IMAGE_SUPPORTED=false)
  - folder: Ruta absoluta para guardar la imagen/SVG (requerida cuando CONTENT_IMAGE_SUPPORTED=false)

El comportamiento de la herramienta generate depende de la variable de entorno CONTENT_IMAGE_SUPPORTED:

Cuando CONTENT_IMAGE_SUPPORTED=true (por defecto): La herramienta devuelve la imagen/SVG directamente en la respuesta
Cuando CONTENT_IMAGE_SUPPORTED=false: La herramienta guarda la imagen/SVG en la carpeta especificada y devuelve la ruta del archivo

Variables de Entorno

CONTENT_IMAGE_SUPPORTED: Controla si las imágenes se devuelven directamente en la respuesta o se guardan en disco
- true (por defecto): Las imágenes se devuelven directamente en la respuesta
- false: Las imágenes se guardan en disco, requiriendo los parámetros name y folder

Ejemplos

Uso Básico

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

Con Tema y Color de Fondo

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

Guardar en Disco (cuando CONTENT_IMAGE_SUPPORTED=false)

// Generate a class diagram and save it to disk as PNG
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

Generar Salida SVG

// Generate a state diagram as SVG
{
  "code": "stateDiagram-v2\n    [*] --> Still\n    Still --> [*]\n    Still --> Moving\n    Moving --> Still\n    Moving --> Crash\n    Crash --> [*]",
  "outputFormat": "svg",
  "name": "state_diagram",
  "folder": "/path/to/diagrams"
}

Preguntas Frecuentes

¿No soporta ya Claude desktop mermaid mediante canvas?

Sí, pero no soporta las opciones theme y backgroundColor. Además, tener un servidor dedicado facilita la creación de diagramas de mermaid con diferentes clientes MCP.

¿Por qué necesito especificar CONTENT_IMAGE_SUPPORTED=false cuando uso Cursor?

Cursor aún no soporta imágenes en línea en las respuestas.

Publicación

Este proyecto utiliza GitHub Actions para automatizar el proceso de publicación en npm.

Método 1: Usar el Script de Publicación (Recomendado)

Asegúrate de que todos tus cambios estén confirmados y enviados

Ejecuta el script de publicación con un número de versión específico o un incremento de versión semántica:

# Using a specific version number
npm run release 0.1.4

# Using semantic version increments
npm run release patch  # Increments the patch version (e.g., 0.1.3 → 0.1.4)
npm run release minor  # Increments the minor version (e.g., 0.1.3 → 0.2.0)
npm run release major  # Increments the major version (e.g., 0.1.3 → 1.0.0)

El script:
- Validará el formato de versión o el incremento semántico
- Comprobará si estás en la rama main
- Detectará y advertirá sobre discrepancias de versión entre archivos
- Actualizará todas las referencias de versión de forma consistente (package.json, package-lock.json e index.ts)
- Creará un único commit con todos los cambios de versión
- Creará y enviará una etiqueta git
- El flujo de trabajo de GitHub compilará y publicará automáticamente en npm

Método 2: Proceso Manual

Actualiza tu código y confirma los cambios

Crea y envía una nueva etiqueta con el número de versión:

git tag v0.1.4  # Use the appropriate version number
git push origin v0.1.4

El flujo de trabajo de GitHub automáticamente:
- Compilará el proyecto
- Publicará en npm con la versión de la etiqueta

Nota: Debes configurar el secreto NPM_TOKEN en la configuración de tu repositorio de GitHub. Para hacerlo:

Genera un token de acceso de npm con permisos de publicación
Ve a tu repositorio de GitHub → Settings → Secrets and variables → Actions
Crea un nuevo secreto de repositorio llamado NPM_TOKEN con tu token de npm como valor

Insignias

Licencia

MIT