Obsidian Brain

obsidian-brain

一个独立的 Node MCP 服务，可让 Claude（以及任何其他 MCP 客户端）通过 Obsidian 知识库实现语义搜索 + 知识图谱 + 知识库编辑。作为单个本地 stdio 进程运行——无需插件、无需 HTTP 桥接、无需 API 密钥，也无需托管服务。你的知识库内容永远不会离开你的设备。

📖 完整文档 → sweir1.github.io/obsidian-brain 配套插件 → sweir1/obsidian-brain-plugin（可选——解锁 active_note、dataview_query、base_query）

目录 — 为什么选择它 · 快速开始 · 你将获得什么 · 工作原理 · 配套插件 · 故障排除 · 近期发布

为什么选择 obsidian-brain？

• 无需运行 Obsidian——与基于 Local REST API 的服务不同，obsidian-brain 直接从磁盘读取 .md 文件。Obsidian 可以关闭；你的知识库只是一个文件夹。
• 核心功能无需 Local REST API 插件——无需在 Obsidian 中安装任何内容。
• 基于分块的语义搜索，结合 RRF 混合检索——以 Markdown 标题为粒度生成嵌入，并通过 Reciprocal Rank Fusion 与 FTS5 BM25 融合。找到精确的分块，并按语义排序。
• 唯一支持 PageRank + Louvain + 图分析的 Obsidian MCP 服务——查询知识库中影响力最大的笔记、桥接笔记和主题集群。其他服务都没有提供这些功能。
• 使用 Ollama 提供高质量本地嵌入——只需设置一个环境变量，即可切换到 qwen3-embedding:0.6b、nomic-embed-text、bge-m3 等模型。
• 一次 npx 安装全部搞定——无需克隆、构建、API 密钥或托管端点。知识库内容永远不会离开你的设备。

快速开始

一行安装（macOS + Claude Desktop）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"

如果你尚未安装 Homebrew + Node 20+，安装程序会为你安装；添加 Claude Desktop 所需的 /usr/local/bin 符号链接；将 obsidian-brain 合并到你的 claude_desktop_config.json；打开“完全磁盘访问权限”面板供你启用 Claude；然后重新启动 Claude。你只需输入一次 macOS 密码（用于 Homebrew + 符号链接）和一次知识库路径。其余步骤都会自动完成。查看其操作内容：scripts/install.sh。

手动安装

需要 Node 20+ 和一个 Obsidian 知识库（也可以是任何包含 .md 文件的文件夹——不一定要安装 Obsidian）。

将 obsidian-brain 接入你的 MCP 客户端。Claude Desktop 示例（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": ["-y", "obsidian-brain@latest", "server"],
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}

退出 Claude Desktop（macOS 上按 ⌘Q）并重新启动即可。

说明

首次启动时，服务会自动为你的知识库建立索引，并下载一个约 34 MB 的嵌入模型。工具可能需要 30–60 秒才会显示在客户端中。之后启动即可立即使用。

提示

不是开发者？macOS 分步指南详细介绍了 Homebrew、Node、GUI 应用的 PATH 修复以及“完全磁盘访问权限”设置。

其他所有 MCP 客户端（Claude Code、Cursor、VS Code、Jan、Windsurf、Cline、Zed、LM Studio、JetBrains AI、Opencode、Codex CLI、Gemini CLI、Warp）：请参阅在 MCP 客户端中安装。

→ 完整的环境变量参考：配置 → 模型 / 预设 / Ollama 详情：嵌入模型 → 从 aaronsb 的插件迁移：迁移指南

你将获得什么

18 个按用途分组的 MCP 工具：

• 查找与阅读 — search、list_notes、read_note
• 理解图谱 — find_connections、find_path_between、detect_themes、rank_notes
• 写入 — create_note、edit_note、apply_edit_preview、link_notes、move_note、delete_note
• 实时编辑器（需要配套插件）— active_note、dataview_query、base_query
• 维护 — reindex、index_status

→ 参数、示例和响应格式：工具参考

工作原理

flowchart LR
    Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]

    subgraph OB ["obsidian-brain (Node process)"]
        direction TB
        SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
        Vault["<b>Vault on disk</b><br/>your .md files"]
        Vault -->|"parse + embed"| SQL
        SQL -.->|"writes"| Vault
    end

    Client <-->|"stdio JSON-RPC"| OB

检索和写入都通过 SQLite 索引完成：读取耗时仅数微秒，写入会立即落盘，并对受影响的文件进行增量重新索引。嵌入按块生成（按标题感知的递归分块器会保留代码块和 LaTeX 块），而 search 默认的 hybrid 模式会通过互惠排名融合（Reciprocal Rank Fusion），合并块级语义排名与 FTS5 BM25 排名。

→ 深入了解为何选择 stdio、SQLite 和本地嵌入：架构 → 实时监视器的行为与防抖机制：实时更新 → 定时重新索引（macOS launchd / Linux systemd）：定时索引（macOS） · (Linux)

配套插件（可选）

可选的 Obsidian 插件 sweir1/obsidian-brain-plugin 会通过 localhost HTTP 端点公开 Obsidian 实时运行状态，包括当前编辑器、Dataview 结果和 Bases 行。安装插件并运行 Obsidian 后，active_note、dataview_query 和 base_query 即可使用。通过 BRAT 使用仓库 ID sweir1/obsidian-brain-plugin 安装。

插件和服务端的主次版本号必须一致——服务端 v1.7.x 应搭配插件 v1.7.x。补丁版本号不同也没问题。

→ 安全模型、能力握手、Dataview / Bases 功能覆盖范围：配套插件

故障排除

最常见的四种问题：

• Claude Desktop 中显示“Connector has no tools available” — 通常是服务端启动时崩溃。查看 ~/Library/Logs/Claude/mcp-server-obsidian-brain.log。解决方法：npm install -g obsidian-brain@latest，退出 Claude（⌘Q）后重新启动。
• ERR_DLOPEN_FAILED / NODE_MODULE_VERSION 不匹配 — better-sqlite3 是针对不同的 Node ABI 构建的。解决方法：PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3。
• Vault path not configured — 未设置 VAULT_PATH。在客户端配置的 env 块或 shell 中设置它。
• 通过 npx 加载了旧版本（发布后客户端仍显示上一版本）— npx 缓存过期。解决方法：rm -rf ~/.npm/_npx，然后重启客户端。在配置中保留 @latest 可避免此问题。

→ 完整故障排除指南（监视器未触发、索引过期、运行多个客户端、超时、嵌入维度不匹配、日志位置）：docs/troubleshooting.md

近期发布

• v1.7.24（2026-05-16）— embeddings.md BYOM 说明 + 5 项 devDep 更新
• v1.7.23（2026-05-16）— BYOM Ollama 自动拉取门控 + 日志记录全面检查 + SIGTERM 单元测试
• v1.7.22（2026-05-15）— 结构化 stderr（NDJSON）+ Ollama 准备状态 + dependabot 安全更新 + SIGTERM 排空集成测试
• v1.7.21（2026-04-27）— install.sh 保险库选择器修复 + 自动执行 ollama pull + 文档/测试完善
• v1.7.20（2026-04-27）— Ollama 前缀查找错误 + 13 项审查完善

→ 完整变更日志：docs/CHANGELOG.md · 后续计划：docs/roadmap.md · 从源代码构建：docs/development.md

致谢

感谢 obra/knowledge-graph 和 aaronsb/obsidian-mcp-plugin，本项目借鉴了它们的创意和代码。此外，还要感谢 Xenova/transformers.js（本地嵌入）、graphology（图分析）和 sqlite-vec（SQLite 中的向量搜索）。

相关项目

• apple-notes-brain — 配套的 macOS Apple Notes MCP 服务：支持读取、写入和搜索，并可在两个方向上完整往返转换 Markdown。

许可证

Apache License 2.0 — 版权所有 2026 sweir1。