obsidian-mermaid-mcp
obsidian-mermaid-mcp
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
```mermaidde 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
.mmdcomo 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(admiteassets/${filename}relativo a la carpeta,attachmentsen la raíz de la bóveda y configuraciones en la misma carpeta) sin configuración.⚡ Dos modos de funcionamiento
Modo observador automático (observador de archivos en segundo plano para una escritura fluida)
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.0Chrome / 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 testInstalació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 3000Nota:
--applyes 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:
macOS (LaunchAgent): consulte
examples/daemons/com.obsidian-mermaid.watch.plistLinux (servicio de usuario systemd): consulte
examples/daemons/obsidian-mermaid-watch.serviceWindows (Programador de tareas / PowerShell): consulte
examples/daemons/register-task-windows.bat
👉 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 |
| preview | Escanea los bloques Mermaid de una nota, los renderiza a SVG e inserta marcadores de incrustación (requiere |
| preview | Restaura los marcadores de incrustación SVG gestionados a los bloques de código Mermaid originales. |
| read-only | Renderiza el código fuente Mermaid sin procesar a un SVG saneado. |
| 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/chapter1o 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 (svgommd).
🔍 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
.mmdgenerado en la carpetaassets/. 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Let Claude, Cursor, or ChatGPT author Mermaid diagrams your team can read and share.
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Create and manage Mermaid.js flowcharts and diagrams with AI agents via MCP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.164 npm1MIT
- AlicenseAqualityDmaintenanceConverts 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.3MIT
- AlicenseAqualityCmaintenanceEnables AI hosts to generate and open Mermaid diagram links in Markdown files, providing tools for syncing, listing, and injecting diagrams via the Mermaid.ai editor.4MIT

diag2md-mcpofficial
AlicenseAqualityCmaintenanceEnables AI coding agents to discover, convert, and synchronize Draw.io C4 and UML diagrams into Mermaid Markdown, providing architectural context and guardrails during chat sessions.310 npmMIT