obsidian-mermaid-mcp

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.

🚀 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

🛠️ Usage Mode 1: Automatic Watcher (Recommended)

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:

• macOS (LaunchAgent): See examples/daemons/com.obsidian-mermaid.watch.plist

• Linux (systemd user service): See examples/daemons/obsidian-mermaid-watch.service

• Windows (Task Scheduler / PowerShell): See examples/daemons/register-task-windows.bat

👉 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

📁 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.