Servidor MCP Claude Mermaid

Servidor MCP para renderizar diagramas Mermaid en Claude Code con funcionalidad de recarga en vivo y una habilidad integrada para obtener orientación experta.

Renderiza diagramas automáticamente en tu navegador con actualizaciones en tiempo real a medida que los refinas. Perfecto para el desarrollo iterativo de diagramas y flujos de trabajo de documentación.

✨ Características

• 🔄 Recarga en vivo - Los diagramas se actualizan automáticamente en tu navegador mientras editas

• 🎨 Múltiples formatos de guardado - Exporta a SVG, PNG o PDF

• 🌈 Temas - Elige entre temas predeterminados, forest, dark o neutral

• 📐 Personalizable - Controla dimensiones, escala y colores de fondo

• 🪄 Previsualización interactiva - Desplaza los diagramas arrastrándolos, haz zoom con los controles del navegador, restablece la posición con un clic

• ⬇️ Exportación desde el navegador - Descarga diagramas como SVG o PNG directamente desde la previsualización

• 🗂️ Previsualizaciones múltiples - Usa preview_id para trabajar en varios diagramas simultáneamente

• 💾 Archivos de trabajo persistentes - Las previsualizaciones en vivo se almacenan en ~/.config/claude-mermaid/live

• 🤖 Habilidad integrada - Incluye una habilidad de Claude con mejores prácticas y orientación experta para crear diagramas

Related MCP server: mcp-mermaid-validator

Arquitectura

🚀 Inicio rápido

1. Instalación

Instalación del plugin (Recomendado)

En Claude Code, añade el marketplace e instala el plugin:

/plugin marketplace add veelenga/claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Luego reinicia Claude Code para activar el plugin.

Desde npm:

npm install -g claude-mermaid

Desde el código fuente:

git clone https://github.com/veelenga/claude-mermaid.git
cd claude-mermaid
npm install && npm run build && npm install -g .

2. Verificar la instalación

Instalación del plugin: El servidor MCP se configura automáticamente. Solo verifica:

/mcp

Deberías ver mermaid en la lista de servidores MCP.

Instalación npm: Configura el servidor MCP manualmente:

claude mcp add --scope user mermaid claude-mermaid

Luego verifica:

claude mcp list

Deberías ver mermaid: claude-mermaid - ✓ Connected

🔌 Otras configuraciones de clientes MCP

Aunque este servidor está optimizado para Claude Code, puede funcionar con cualquier cliente compatible con MCP. Aquí te explicamos cómo configurarlo para otras herramientas populares:

Añádelo a tu archivo de configuración MCP de Codex (~/.codex/mcp_settings.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

O configúralo a través de la CLI de Codex:

codex mcp add mermaid claude-mermaid

Añádelo a tu archivo de configuración MCP de Cursor (.cursor/mcp.json o ajustes):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

O usa la interfaz de ajustes de Cursor:

1. Abre los ajustes de Cursor (Cmd/Ctrl + ,)

2. Navega a MCP Servers

3. Añade un nuevo servidor con el comando: claude-mermaid

Si usas la extensión Cline para VSCode:

1. Abre los ajustes de VSCode (Cmd/Ctrl + ,)

2. Busca "Cline MCP"

3. Añade al JSON de ajustes de MCP:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Añádelo al archivo de configuración MCP de Windsurf:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

La ubicación de la configuración varía según la plataforma:

• macOS: ~/Library/Application Support/Windsurf/mcp.json

• Linux: ~/.config/windsurf/mcp.json

• Windows: %APPDATA%\Windsurf\mcp.json

Añádelo al archivo de configuración MCP de Gemini CLI (~/.gemini/mcp.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

O usa la CLI de Gemini para configurar:

gemini config mcp add mermaid --command claude-mermaid

Para cualquier cliente compatible con MCP, usa la configuración estándar:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

El comando claude-mermaid debería estar disponible en tu PATH después de la instalación.

Nota: Algunos clientes pueden requerir la ruta completa al ejecutable:

• Encuentra la ruta: which claude-mermaid (Unix/macOS) o where claude-mermaid (Windows)

• Usa la ruta absoluta en la configuración: "command": "/ruta/a/claude-mermaid"

💡 Uso

Simplemente pide a Claude Code que cree diagramas Mermaid de forma natural. Cuando se instala como plugin, la habilidad integrada mermaid-diagrams proporciona orientación experta, mejores prácticas y gestión automática del flujo de trabajo.

Ejemplos básicos

"Create a Mermaid diagram showing the user authentication flow"
"Draw a sequence diagram for the payment process"
"Generate a flowchart for the deployment pipeline"

Ejemplos avanzados

Con formato personalizado:

"Create a dark theme architecture diagram with transparent background"
"Generate a forest theme flowchart and save to ./docs/flow.svg"

Con formato de salida específico:

"Create an ER diagram and save as PDF to ./docs/schema.pdf"
"Save the flowchart as PNG to ./docs/flow.png"

Nota: El navegador siempre muestra SVG para la previsualización en vivo, mientras que guarda en el formato que elijas.

Refinamiento iterativo:

"Create a class diagram for the User module"
// Browser opens with live preview
"Add the Address and Order classes with relationships"
// Diagram updates automatically in browser!

Ejemplo completo

"Create a flowchart and save to ./docs/auth-flow.svg:

graph LR
    A[User Login] --> B{Valid Credentials?}
    B -->|Yes| C[Access Granted]
    B -->|No| D[Access Denied]
    C --> E[Dashboard]
    D --> F[Try Again]

    style A fill:#e1f5ff
    style C fill:#d4edda
    style D fill:#f8d7da
"

El diagrama se guardará en ./docs/auth-flow.svg y se abrirá en tu navegador con la recarga en vivo activada.

🔧 Herramientas y parámetros

Hay dos herramientas expuestas por el servidor MCP:

1. mermaid_preview — renderiza y abre una previsualización en vivo

• diagram (string, requerido) — Código del diagrama Mermaid

• preview_id (string, requerido) — Identificador para esta sesión de previsualización. Usa IDs diferentes para múltiples diagramas simultáneos (ej. architecture, flow).

• format (string, por defecto svg) — Uno de svg, png, pdf. La previsualización en vivo solo está disponible para svg.

• theme (string, por defecto default) — Uno de default, forest, dark, neutral.

• background (string, por defecto white) — Color de fondo. Ejemplos: transparent, white, #F0F0F0.

• width (number, por defecto 800) — Ancho del diagrama en píxeles.

• height (number, por defecto 600) — Altura del diagrama en píxeles.

• scale (number, por defecto 2) — Factor de escala para una salida de mayor calidad.

2. mermaid_save — guarda el diagrama en vivo actual en una ruta

• save_path (string, requerido) — Ruta de destino (ej. ./docs/diagram.svg).

• preview_id (string, requerido) — Debe coincidir con el preview_id usado en mermaid_preview.

• format (string, por defecto svg) — Uno de svg, png, pdf. Si el archivo de trabajo en vivo para este formato aún no existe, se renderiza bajo demanda antes de guardarlo.

🎯 Cómo funciona la recarga en vivo

1. Primer renderizado: Abre el diagrama en el navegador en http://localhost:3737/{preview_id}

2. Realizar cambios: Edita el diagrama a través de Claude Code

3. Auto-actualización: El navegador detecta cambios a través de WebSocket y recarga

4. Indicador de estado: Punto verde = conectado, Punto rojo = reconectando

El servidor en vivo utiliza los puertos 3737-3747 y encuentra automáticamente un puerto disponible.

Controles de previsualización en vivo

• Desplazamiento: Haz clic y arrastra el diagrama para moverlo

• Zoom: Usa el zoom del navegador (Ctrl/Cmd + +/- o pellizcar para hacer zoom en el trackpad)

• Restablecer posición: Haz clic en el botón ⊙ en la barra de estado para recentrar el diagrama

• Exportar: Haz clic en el botón ⬇ para descargar como SVG o PNG

Notas

• La previsualización en vivo solo está disponible para el formato svg; PNG/PDF se renderizan sin recarga en vivo.

• Para diagramas de secuencia, Mermaid no admite directivas style dentro de sequenceDiagram.

🖥️ Servidor independiente

Puedes iniciar el servidor de previsualización sin un agente de IA usando el flag --serve:

claude-mermaid --serve

Esto abre la galería de diagramas en tu navegador con todos los diagramas renderizados anteriormente. Útil para navegar y exportar diagramas fuera de una sesión de Claude Code.

🛠️ Desarrollo

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

# Start the MCP server directly
npm start

📝 Solución de problemas

Error: Cannot find package 'puppeteer':

Este es un problema poco común específico del entorno. Prueba estas soluciones:

1. Instala claude-mermaid globalmente:

npm install -g claude-mermaid

2. Reinstala el plugin en Claude Code:

/plugin uninstall claude-mermaid
/plugin install claude-mermaid@claude-mermaid

El servidor no se conecta:

# Check if server is installed
claude-mermaid -v

# Reinstall if needed
npm install -g claude-mermaid

# Verify MCP configuration
claude mcp list

Error de permiso denegado:

# Make sure the binary is executable
chmod +x $(which claude-mermaid)

Puerto ya en uso:

• El servidor utiliza los puertos 3737-3747

• Encontrará automáticamente un puerto disponible

• Comprueba si otro proceso está usando estos puertos: lsof -i :3737-3747

Los diagramas no se renderizan o la recarga en vivo no funciona:

El servidor registra los logs en ~/.config/claude-mermaid/logs/:

• mcp.log - Solicitudes de herramientas y renderizado de diagramas

• web.log - Conexiones HTTP/WebSocket y recarga en vivo

Habilita el registro de depuración en tu configuración MCP:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid",
      "env": {
        "CLAUDE_MERMAID_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Luego revisa los logs:

# View MCP operations
tail -f ~/.config/claude-mermaid/logs/mcp.log

# View WebSocket connections
tail -f ~/.config/claude-mermaid/logs/web.log

Niveles de registro disponibles: DEBUG, INFO (por defecto), WARN, ERROR, OFF

🤝 Contribución

¡Las contribuciones son bienvenidas! Por favor, siéntete libre de enviar un Pull Request.

📄 Licencia

MIT - consulta el archivo LICENSE para más detalles

🔗 Enlaces

• Repositorio en GitHub

• Paquete npm

• Documentación de Claude Code

• Documentación de Mermaid

👀 Ver también

Si te gusta este proyecto, también podría interesarte

• preview-skills — habilidades de previsualización para visualizar archivos en el navegador (markdown, csv, json, mermaid y más)

Despliegue alojado

Un despliegue alojado está disponible en Fronteir AI.