obsidian-mermaid-mcp

本地、零 Token、无损的 Mermaid 渲染与可逆笔记同步，适用于所有 AI Agent 的 Obsidian 仓库。

🌟 核心亮点

• ✍️ 零提示词的 Agent 写作体验 AI Agent（Codex、Claude Code、Antigravity、Cursor、Windsurf、Cline 等）可以自然地编写包含 ```mermaid 代码块的标准 Markdown。后台 Watcher 会在约 2 秒内自动将其转换为内嵌 SVG，无需特殊提示词。

• 🔒 100% 本地与隐私安全 通过无头 Chrome/Puppeteer 在本地渲染。无云端渲染 API、无 Token 成本、零网络泄露。

• 🔄 无损且完全可逆 原始 Mermaid 代码安全保存在 .mmd 侧车文件与 SVG <metadata> 中。可随时一键还原为原始 Mermaid 代码块。

• 🧠 智能仓库适配 自动检测 .obsidian/app.json（支持文件夹相对 assets/${filename}、仓库根目录 attachments 及同目录配置），零配置即可使用。

• ⚡ 双操作模式

  1. 自动 Watcher 模式（后台文件监听，实现无缝写作）

  2. MCP 工具模式（4 个标准 stdio MCP 工具，供 Agent 直接调用）

• 💻 全平台支持 macOS、Linux、Windows、WSL 及 Docker。

🚀 快速开始

环境要求

• Node.js：>= 20.0.0

• Chrome / Chromium / Edge / Brave / Arc：安装在标准位置，或通过 PUPPETEER_EXECUTABLE_PATH 指定。

安装与构建（本地 Node.js）

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

安装与构建（Docker 替代方案）

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

👉 详细 Docker 指南（MCP Server 与 Docker Compose）：docs/docker-guide.md

🛠️ 使用模式 1：自动 Watcher（推荐）

在后台运行 watcher，自动转换 Obsidian 笔记中新建或编辑的 Mermaid 代码块。

前台测试

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

注意：实际写入文件需要 --apply 参数。未使用 --apply 时，watcher 仅以预览模式运行。

后台守护进程设置

我们为所有主流平台提供了开箱即用的后台服务模板：

• macOS（LaunchAgent）：参见 examples/daemons/com.obsidian-mermaid.watch.plist

• Linux（systemd 用户服务）：参见 examples/daemons/obsidian-mermaid-watch.service

• Windows（任务计划程序 / PowerShell）：参见 examples/daemons/register-task-windows.bat

👉 详细守护进程设置指南：docs/daemon-setup.md

🔌 使用模式 2：MCP 工具模式

将 obsidian-mermaid-mcp 配置为你喜爱的 AI 宿主中的标准 MCP 服务器。

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

👉 10+ 种 AI 宿主（Codex、Claude Code、Cursor、Windsurf、Cline、Roo Code、Goose、Zed 等）的完整配置指南： 参见 docs/host-configs.md。

可用 MCP 工具

📁 工作原理：仓库转换

转换前（标准 Markdown）

# Architecture Overview

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

转换后（干净的内嵌 SVG + 侧车文件）

# Architecture Overview

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

生成的文件结构

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

⚙️ 配置参考

你可以通过 JSON 配置文件（--config /path/to/config.json）或环境变量自定义行为。

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

模板占位符

• {note_dir}：笔记相对于仓库根目录的子目录（例如 SEM_AI/chapter1，根目录笔记则为空）。

• {note_name}：笔记的安全文件名（不含 .md 扩展名）。

• {asset_root}：配置的资源根目录（默认：assets）。

• {index}：笔记中图表的 3 位序号（001、002 等）。

• {hash}：Mermaid 源码的 16 位 SHA-256 指纹。

• {ext}：文件扩展名（svg 或 mmd）。

🔍 故障排查与常见问题

1. 找不到浏览器

默认情况下，服务器会在 macOS、Linux 和 Windows 的标准目录中搜索 Google Chrome、Chromium、Microsoft Edge、Brave 或 Arc。如果安装在自定义位置，请设置：

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

或在 config.json 中指定 "renderer.executablePath"。

2. 深色主题支持

在 config.json 中设置 "theme": "dark"，或在 MCP 工具调用中传入 "theme": "dark"。你也可以使用 "theme": "auto" 配合 "themeContext": "dark"。

3. 如何编辑已转换的图表

• 方案 A：运行 restore_note（通过 MCP 或 CLI）将笔记还原为 ```mermaid 代码块，编辑后让其重新同步。

• 方案 B：直接编辑 assets/ 文件夹中生成的 .mmd 侧车文件。Watcher / 同步引擎会自动检测侧车文件变更并重新生成 SVG！

📄 许可证

MIT 许可证。详情参见 LICENSE。