Skip to main content
Glama
obsidian-mermaid-mcp

obsidian-mermaid-mcp

by IPromise-23

obsidian-mermaid-mcp

License: MIT Node: >=20 MCP Ready Platform

Local, Zero-Token, Lossless Mermaid rendering and reversible note synchronization for Obsidian vaults across all AI Agents.


🌟 Key Highlights

  • ✍️ Zero-Prompt Agent Writing Experience AI Agents (Codex, Claude Code, Antigravity, Cursor, Windsurf, Cline, etc.) can write standard Markdown with ```mermaid code blocks naturally. The background Watcher automatically converts them to embedded SVGs within ~2 seconds without requiring special prompts.

  • πŸ”’ 100% Local & Private Renders locally via headless Chrome/Puppeteer. No cloud rendering APIs, no token costs, and zero network leaks.

  • πŸ”„ Lossless & Fully Reversible Original Mermaid code is safely preserved in both .mmd sidecar files and SVG <metadata>. Revert back to original Mermaid code blocks anytime with one click.

  • 🧠 Smart Vault Adaptation Automatically detects .obsidian/app.json (supports folder-relative assets/${filename}, vault-root attachments, and same-folder setups) with zero configuration.

  • ⚑ Dual Operation Modes

    1. Automatic Watcher Mode (background file watcher for seamless authoring)

    2. MCP Tool Mode (4 standard stdio MCP tools for direct Agent invocation)

  • πŸ’» Universal Platform Support macOS, Linux, Windows, WSL, and Docker.


Related MCP server: Vizdown-MCP

πŸš€ Quick Start

Requirements

  • Node.js: >= 20.0.0

  • Chrome / Chromium / Edge / Brave / Arc: Installed in a standard location, or specify via PUPPETEER_EXECUTABLE_PATH.

Installation & Build (Local Node.js)

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

Installation & Build (Docker Alternative)

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

πŸ‘‰ Detailed Docker Guide (MCP Server & Docker Compose): docs/docker-guide.md


Run the watcher in the background to automatically convert any newly written or edited Mermaid blocks in your Obsidian notes.

Foreground Test

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

Note: --apply is required for actual file writes. Without --apply, the watcher operates in preview-only mode.

Background Daemon Setup

We provide ready-to-use background service templates for all major platforms:

πŸ‘‰ Detailed Daemon Setup Guide: docs/daemon-setup.md


πŸ”Œ Usage Mode 2: MCP Tool Mode

Configure obsidian-mermaid-mcp as a standard MCP server in your favorite AI host.

MCP Configuration Example

{
  "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"
      }
    }
  }
}

πŸ‘‰ Complete Configuration Guide for 10+ AI Hosts (Codex, Claude Code, Cursor, Windsurf, Cline, Roo Code, Goose, Zed, etc.): See docs/host-configs.md.

Available MCP Tools

Tool Name

Default Mode

Description

sync_note

preview

Scan Mermaid fences in a note, render to SVG, and insert embed markers (requires apply: true to write).

restore_note

preview

Restore managed SVG embed markers back to original Mermaid code fences.

render_mermaid

read-only

Render raw Mermaid source to sanitized SVG.

extract_mermaid_source

read-only

Extract or recover Mermaid source from a note or managed SVG file.


πŸ“ How It Works: Vault Transformation

Before Conversion (Standard Markdown)

# Architecture Overview

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

After Conversion (Clean Embedded SVG + Sidecar)

# Architecture Overview

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

Generated File Structure

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

βš™οΈ Configuration Reference

You can customize behavior via a JSON configuration file (--config /path/to/config.json) or environment variables.

Example 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
  }
}

Template Placeholders

  • {note_dir}: Subdirectory of the note relative to vault root (e.g. SEM_AI/chapter1 or empty for root notes).

  • {note_name}: Safe filename of the note without .md extension.

  • {asset_root}: Configured asset root (default: assets).

  • {index}: 3-digit index of the diagram within the note (001, 002, etc.).

  • {hash}: 16-character SHA-256 fingerprint of the Mermaid source.

  • {ext}: File extension (svg or mmd).


πŸ” Troubleshooting & FAQ

1. Browser not found

By default, the server searches standard macOS, Linux, and Windows directories for Google Chrome, Chromium, Microsoft Edge, Brave, or Arc. If installed in a custom location, set:

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

Or specify "renderer.executablePath" in your config.json.

2. Dark theme support

Set "theme": "dark" in config.json or pass "theme": "dark" in MCP tool calls. You can also use "theme": "auto" with "themeContext": "dark".

3. How to edit an already converted diagram

  • Option A: Run restore_note (via MCP or CLI) to restore the note back to ```mermaid code blocks, edit it, and let it re-sync.

  • Option B: Directly edit the generated .mmd sidecar file in the assets/ folder. The Watcher / Sync engine will automatically detect the sidecar change and regenerate the SVG!


πŸ“„ License

MIT License. See LICENSE for details.

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
      68 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