Skip to main content
Glama
obsidian-mermaid-mcp

obsidian-mermaid-mcp

by IPromise-23

obsidian-mermaid-mcp

License: MIT Node: >=20 MCP Ready Platform

Renderizado local de Mermaid sin tokens y sin pérdidas, y sincronización reversible de notas para bóvedas de Obsidian en todos los agentes de IA.


🌟 Características principales

  • ✍️ Experiencia de escritura para agentes sin prompts Los agentes de IA (Codex, Claude Code, Antigravity, Cursor, Windsurf, Cline, etc.) pueden escribir Markdown estándar con bloques de código ```mermaid de forma natural. El observador en segundo plano los convierte automáticamente en SVG incrustados en ~2 segundos sin necesidad de prompts especiales.

  • 🔒 100% local y privado Se renderiza localmente mediante Chrome/Puppeteer sin interfaz gráfica. Sin APIs de renderizado en la nube, sin costes de tokens y sin fugas de red.

  • 🔄 Sin pérdidas y totalmente reversible El código Mermaid original se conserva de forma segura tanto en archivos laterales .mmd como en el <metadata> del SVG. Revierta al bloque de código Mermaid original en cualquier momento con un clic.

  • 🧠 Adaptación inteligente a la bóveda Detecta automáticamente .obsidian/app.json (admite assets/${filename} relativo a la carpeta, attachments en la raíz de la bóveda y configuraciones en la misma carpeta) sin configuración.

  • ⚡ Dos modos de funcionamiento

    1. Modo observador automático (observador de archivos en segundo plano para una escritura fluida)

    2. Modo herramienta MCP (4 herramientas MCP estándar de stdio para invocación directa por parte del agente)

  • 💻 Soporte universal de plataformas macOS, Linux, Windows, WSL y Docker.


Related MCP server: Vizdown-MCP

🚀 Inicio rápido

Requisitos

  • Node.js: >= 20.0.0

  • Chrome / Chromium / Edge / Brave / Arc: instalado en una ubicación estándar, o especifíquelo mediante PUPPETEER_EXECUTABLE_PATH.

Instalación y compilación (Node.js local)

git clone https://github.com/IPromise-23/obsidian-mermaid-mcp.git
cd obsidian-mermaid-mcp
npm ci
npm run build
npm test

Instalación y compilación (alternativa con Docker)

git clone https://github.com/IPromise-23/obsidian-mermaid-mcp.git
cd obsidian-mermaid-mcp
docker build -t obsidian-mermaid-mcp:latest .

👉 Guía detallada de Docker (servidor MCP y Docker Compose): docs/docker-guide.md


🛠️ Modo de uso 1: Observador automático (recomendado)

Ejecute el observador en segundo plano para convertir automáticamente cualquier bloque Mermaid recién escrito o editado en sus notas de Obsidian.

Prueba en primer plano

node packages/watcher/dist/index.js watch \
  --vault-root /path/to/your/obsidian/vault \
  --apply \
  --debounce-ms 3000

Nota: --apply es necesario para escribir realmente en los archivos. Sin --apply, el observador funciona solo en modo de vista previa.

Configuración del demonio en segundo plano

Proporcionamos plantillas de servicios en segundo plano listas para usar para todas las plataformas principales:

👉 Guía detallada de configuración del demonio: docs/daemon-setup.md


🔌 Modo de uso 2: Modo herramienta MCP

Configure obsidian-mermaid-mcp como un servidor MCP estándar en su host de IA favorito.

Ejemplo de configuración MCP

{
  "mcpServers": {
    "obsidian-mermaid": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mermaid-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_MERMAID_VAULT_ROOT": "/absolute/path/to/your/vault"
      }
    }
  }
}

👉 Guía de configuración completa para más de 10 hosts de IA (Codex, Claude Code, Cursor, Windsurf, Cline, Roo Code, Goose, Zed, etc.): Consulte docs/host-configs.md.

Herramientas MCP disponibles

Nombre de la herramienta

Modo predeterminado

Descripción

sync_note

preview

Escanea los bloques Mermaid de una nota, los renderiza a SVG e inserta marcadores de incrustación (requiere apply: true para escribir).

restore_note

preview

Restaura los marcadores de incrustación SVG gestionados a los bloques de código Mermaid originales.

render_mermaid

read-only

Renderiza el código fuente Mermaid sin procesar a un SVG saneado.

extract_mermaid_source

read-only

Extrae o recupera el código fuente Mermaid de una nota o de un archivo SVG gestionado.


📁 Cómo funciona: Transformación de la bóveda

Antes de la conversión (Markdown estándar)

# Architecture Overview

```mermaid
flowchart LR
    Client --> Server
    Server --> Database
```

Después de la conversión (SVG incrustado limpio + archivo lateral)

# Architecture Overview

![[assets/Architecture/mermaid-001-f97437d9e714d8ee.svg|600]]

Estructura de archivos generada

MyVault/
├── Architecture.md
└── assets/
    └── Architecture/
        ├── mermaid-001-f974.svg   # Sanitized, high-resolution SVG
        └── mermaid-001-f974.mmd   # Exact Mermaid source backup

⚙️ Referencia de configuración

Puede personalizar el comportamiento mediante un archivo de configuración JSON (--config /ruta/a/config.json) o variables de entorno.

Ejemplo de config.json:

{
  "configVersion": 1,
  "vaultRoot": "/path/to/vault",
  "assetRoot": "assets",
  "attachmentPattern": "{note_dir}/assets/{note_name}/mermaid-{index}-{hash}.svg",
  "sourcePattern": "{note_dir}/assets/{note_name}/mermaid-{index}-{hash}.mmd",
  "embedWidth": 600,
  "theme": "default",
  "background": "transparent",
  "sourceStorage": "both",
  "failurePolicy": "partial",
  "renderer": {
    "timeoutMs": 30000,
    "browserIdleTimeoutMs": 300000,
    "maxConcurrentRenders": 1,
    "htmlLabels": false,
    "securityLevel": "strict",
    "executablePath": ""
  },
  "watcher": {
    "enabled": true,
    "debounceMs": 3000,
    "apply": true
  }
}

Marcadores de posición de plantilla

  • {note_dir}: subdirectorio de la nota relativo a la raíz de la bóveda (p. ej., SEM_AI/chapter1 o vacío para notas raíz).

  • {note_name}: nombre de archivo seguro de la nota sin la extensión .md.

  • {asset_root}: raíz de activos configurada (por defecto: assets).

  • {index}: índice de 3 dígitos del diagrama dentro de la nota (001, 002, etc.).

  • {hash}: huella digital SHA-256 de 16 caracteres del código fuente Mermaid.

  • {ext}: extensión de archivo (svg o mmd).


🔍 Solución de problemas y preguntas frecuentes

1. No se encuentra el navegador

Por defecto, el servidor busca en los directorios estándar de macOS, Linux y Windows Google Chrome, Chromium, Microsoft Edge, Brave o Arc. Si está instalado en una ubicación personalizada, establezca:

export PUPPETEER_EXECUTABLE_PATH="/custom/path/to/chrome"

O especifique "renderer.executablePath" en su config.json.

2. Soporte de tema oscuro

Establezca "theme": "dark" en config.json o pase "theme": "dark" en las llamadas a las herramientas MCP. También puede usar "theme": "auto" con "themeContext": "dark".

3. Cómo editar un diagrama ya convertido

  • Opción A: ejecute restore_note (mediante MCP o CLI) para restaurar la nota a los bloques de código ```mermaid, edítela y deje que se vuelva a sincronizar.

  • Opción B: edite directamente el archivo lateral .mmd generado en la carpeta assets/. El observador / motor de sincronización detectará automáticamente el cambio en el archivo lateral y regenerará el SVG.


📄 Licencia

Licencia MIT. Consulte LICENSE para más detalles.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to generate and render Mermaid diagrams (flowcharts, sequence diagrams, etc.) as PNG/SVG images with local file saving and HTTP access URLs. Supports batch processing and intelligent caching for efficient diagram creation.
      1
      64 npm
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Converts Markdown files into professional diagrams such as flowcharts, mind maps, and architecture diagrams using Mermaid.js and custom SVG renderers. It enables users to list, render, and export visualizations in multiple formats including SVG, PNG, and PDF.
      3
      MIT