Obsidian Semantic Search

Obsidian 语义搜索 MCP

为需要在 Obsidian 笔记中找到合适内容、但不需要写入权限的 Agent 提供只读语义检索。

한국어 · 快速开始 · 为什么要做这个项目 · 工作原理

---

只有 Agent 能找到合适的笔记，Obsidian 知识库才真正有用。

关键词搜索容易遗漏上下文。功能完备、支持写入的 Obsidian MCP 服务，提供的能力超出了检索 Agent 的需求。Obsidian 插件在 Obsidian 内使用很方便，但对于 Codex、Claude Desktop、Cursor 或其他 MCP 客户端而言，它们并不总是合适的边界。

这个项目提供精简方案：

local Obsidian vault -> read-only scanner -> local SQLite index -> MCP search/read tools

不写入笔记。默认不使用云端嵌入。不需要 Obsidian 插件运行时。不需要同步服务。

状态：0.3.1 早期预览版。服务目前可用，但在 1.0 之前，排序行为和工具架构可能会发生变化。

你将获得什么

需求	此服务的功能
找到 Agent 应该阅读的笔记	对 Markdown 笔记进行语义 + 关键词混合搜索
确保知识库安全	仅提供搜索、读取、索引和状态功能；不提供写入、修补、移动、重命名或删除工具
采用本地优先方式	使用 Ollama 嵌入模型，并将索引存储在本机
让结果更适合 Agent 使用	返回文件级匹配项，包含标题、摘录和行范围
避免依赖插件状态	直接从文件系统读取知识库；无需运行 Obsidian

结果示例：

{
  "path": "02_Projects/RealtimeAPI/05_Interview_QA.md",
  "title": "Interview Q&A",
  "score": 0.7431,
  "matched_sections": [
    {
      "heading": "Level 4 > Redis Lua atomicity",
      "lines": [266, 305],
      "reason": "semantic=1, keyword=0.5565, metadata=0.6"
    }
  ]
}

快速开始

要求：

• Node.js >= 24
• Ollama
• Obsidian 知识库
• MCP 客户端，例如 Codex、Claude Desktop、Cursor 或其他 stdio MCP 客户端

安装嵌入模型：

ollama pull bge-m3
curl http://localhost:11434/api/tags

打印设置指南：

npx -y --package @dalecb/obsidian-semantic-mcp obsidian-semantic-mcp-setup

Codex 设置

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.obsidian_semantic]
command = "npx"
args = ["-y", "@dalecb/obsidian-semantic-mcp"]

[mcp_servers.obsidian_semantic.env]
OBSIDIAN_VAULT_ROOT = "/path/to/your/Obsidian Vault"
OBSIDIAN_SEMANTIC_MCP_HOME = "/Users/you/.obsidian-semantic-mcp"
OLLAMA_BASE_URL = "http://localhost:11434"
OBSIDIAN_EMBED_MODEL = "bge-m3"
OBSIDIAN_SEMANTIC_AUTO_INDEX = "true"

重启 Codex，然后运行：

obsidian_semantic.index_status
obsidian_semantic.search_notes { "query": "Redis Lua atomicity", "limit": 5 }

Claude Code 设置

在用户级别添加服务，避免将个人知识库路径放入项目的 .mcp.json 文件中：

claude mcp add obsidian_semantic --scope user \
  --env OBSIDIAN_VAULT_ROOT="/path/to/your/Obsidian Vault" \
  --env OBSIDIAN_SEMANTIC_MCP_HOME="/Users/you/.obsidian-semantic-mcp" \
  --env OLLAMA_BASE_URL="http://localhost:11434" \
  --env OBSIDIAN_EMBED_MODEL="bge-m3" \
  --env OBSIDIAN_SEMANTIC_AUTO_INDEX="true" \
  -- npx -y @dalecb/obsidian-semantic-mcp

claude mcp get obsidian_semantic

启动新的 Claude Code 会话并运行 /mcp，确认服务已连接。在原生 Windows 环境中，请在环境标志之后使用 -- cmd /c npx -y @dalecb/obsidian-semantic-mcp。

有关作用域和命令的详细信息，请参阅 Anthropic 的 Claude Code MCP 文档。

Claude Desktop / JSON MCP 客户端设置

在 Claude Desktop 中，打开 设置 → 开发者 → 编辑配置。这会在 macOS 上打开 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上打开 %APPDATA%\Claude\claude_desktop_config.json。将以下服务合并到 mcpServers 中：

{
  "mcpServers": {
    "obsidian_semantic": {
      "command": "npx",
      "args": ["-y", "@dalecb/obsidian-semantic-mcp"],
      "env": {
        "OBSIDIAN_VAULT_ROOT": "/path/to/your/Obsidian Vault",
        "OBSIDIAN_SEMANTIC_MCP_HOME": "/Users/you/.obsidian-semantic-mcp",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OBSIDIAN_EMBED_MODEL": "bge-m3",
        "OBSIDIAN_SEMANTIC_AUTO_INDEX": "true"
      }
    }
  }
}

完全退出并重启 Claude Desktop。Cursor 和其他 JSON 风格的 stdio MCP 客户端也可以使用相同的 mcpServers 条目。在 Windows 上，如果找不到 npx，请使用 "command": "cmd"，并在 args 前添加 "/c", "npx"。

Claude Desktop 配置和日志的相关信息，请参阅官方本地 MCP 服务指南。

为什么要构建此项目

它的目标不是成为功能最强大的 Obsidian 自动化服务，而是成为你可以交给 Agent 的最安全检索工具。

以下是它与通常会拿来比较的两种工具的对比——拥有完整权限的 Obsidian MCP 服务（基于 Local REST API）和 GBrain（更广泛的知识编译平台）：

	本项目	拥有完整权限的 Obsidian MCP	GBrain
访问模式	只读：搜索 / 读取 / 索引	读取 + 写入 + 编辑 + 删除	读取 + 写入；将笔记编译成自己的模型
是否接触你的库	从不	是	是 — 会重构内容
Obsidian 是否必须运行	否 — 直接读取文件	是 — 需要 REST API 插件	否
所需本地运行环境	Node.js + Ollama	Obsidian + 插件	独立平台
嵌入与数据	默认使用本地 Ollama；可配置远程 URL	本地 API；嵌入方式因配置而异	内置管线；可选同步
存储	一个可删除并重建的 SQLite 文件	由插件管理	自有存储 / 迁移
最适用于	为 Agent 提供小型只读检索边界	完整的库自动化与编辑	跨来源构建编译后的知识库

这种取舍是有意为之：放弃写入、编辑和在 Obsidian 内运行，换来更少的组件和更小的影响范围。

如果你希望 Agent 能回答以下问题，请使用此工具：

• “哪个笔记解释了这个项目决策？”
• “找到我写过幂等性负载不匹配的文件。”
• “显示与此面试主题相关的职业笔记。”
• “搜索我的库，但不要对其进行修改。”

如果你想要 Obsidian UI 插件、自动生成笔记或具备写入能力的库自动化，请不要使用此工具。

工具

index_status

返回索引元数据和安全设置。

index_vault

构建或更新外部 SQLite 索引。

{ "mode": "incremental" }

指定文件：

{
  "mode": "incremental",
  "paths": ["02_Projects/My Note.md"]
}

search_notes

使用语义与关键词混合排序搜索笔记。

{
  "query": "live coding notes",
  "limit": 8,
  "mode": "hybrid"
}

模式：

• hybrid：语义向量 + SQLite FTS5 + 元数据加权
• semantic：优先使用向量搜索
• keyword：使用 FTS5 进行关键词搜索，不对查询进行嵌入

read_note

按库内相对路径读取笔记或指定行范围。

{
  "path": "02_Projects/My Note.md",
  "start_line": 10,
  "end_line": 40
}

工作原理

index_vault
  -> scan Markdown files under OBSIDIAN_VAULT_ROOT
  -> block denied paths and symlink escapes
  -> split notes by Markdown headings
  -> create one summary chunk per file
  -> embed chunks with Ollama bge-m3
  -> store notes, chunks, FTS rows, and vectors in SQLite

search_notes
  -> incrementally index on first search or first search after a Markdown change
  -> embed the query with Ollama
  -> score vector similarity
  -> score SQLite FTS5 keyword matches
  -> apply title/path/heading metadata boosts
  -> regroup chunk matches into file-level results

默认存储：

~/.obsidian-semantic-mcp/
  data/semantic.sqlite

库仍是事实来源。SQLite 数据库是派生索引，可以删除并重建。

安全模型

此服务会读取你的库，但从不向其中写入内容。有三层规则决定 Agent 可以看到什么。

1. 始终禁止（系统 / 工具）。 永不索引，无法覆盖：

• .obsidian/、.smart-env/、.claude/、.codex-*/
• 任何隐藏文件夹（名称以 . 开头）
• node_modules、cache、logs

2. 敏感内容 — 默认禁止，可解锁。 即使工具调用传入 include_sensitive: true，仍会保持阻止状态，除非服务以 OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE=true 启动。默认路径为 08_PersonalInfo/。可使用 OBSIDIAN_SEMANTIC_SENSITIVE_PATHS 覆盖列表（以逗号或换行符分隔的文件夹）：

OBSIDIAN_SEMANTIC_SENSITIVE_PATHS = "08_PersonalInfo, 09_Finance"

3. 你自己的排除项 — 始终禁止。 你绝不希望被索引、搜索或读取的文件夹。没有解锁标志：

OBSIDIAN_SEMANTIC_EXCLUDE = "03_Journal, Private, Clients/Acme"

你想选择哪种方式？

• “完全不要索引此内容” → OBSIDIAN_SEMANTIC_EXCLUDE
• “保持锁定，但需要时可以用标志解锁” → OBSIDIAN_SEMANTIC_SENSITIVE_PATHS + OBSIDIAN_SEMANTIC_ALLOW_SENSITIVE

其他防护措施：

• 所有路径都通过 realpath 解析。
• 会阻止路径遍历和 URL 编码的路径遍历。
• 会阻止指向库根目录之外，或指向库内禁止路径的符号链接。

search_notes 和 read_note 会在每次调用时执行当前排除设置。启用自动索引后，下一次搜索也会从索引中移除已排除的过期条目。使用 index_status 确认当前生效的列表。

本地索引会存储片段和嵌入向量。请将其视为库的派生副本。请参阅 PRIVACY.md。

索引策略

默认采用操作驱动，而非基于定时器：

1. 服务启动后首次调用 search_notes。
2. Markdown 文件创建、更新、删除或重命名事件后首次调用 search_notes。
3. 嵌入模型或索引格式变更后首次调用 search_notes；这会触发完整重建。
4. 显式调用 index_vault。

文件系统监视器只会将索引标记为脏。索引会在下一次搜索前立即运行一次，并发搜索会共享这项工作。如果无法进行递归监视，服务会在每次搜索前回退为增量扫描。

使用以下设置禁用自动索引：

OBSIDIAN_SEMANTIC_AUTO_INDEX = "false"

然后自行调用 index_vault { "mode": "incremental" }。仍支持旧版 OBSIDIAN_SEMANTIC_STARTUP_INDEX=true，但这不是默认设置，因为即使后续没有搜索，它也会执行索引。

搜索质量评估

创建一个包含查询和预期路径的 JSON 文件，以便在相同条件下比较关键词、语义和混合模式：

[
  { "query": "strong consistency at 1000 TPS", "expected_paths": ["03_Knowledge/QnA/Strong-Consistency-at-1000TPS.md"] }
]

npm run evaluate -- ./queries.json 5

该命令会报告 Recall@K 和 MRR。除非混合搜索的表现明显优于关键词基线，否则不要增加排序复杂度或嵌入成本。

评估前，使用 search_notes 或 index_vault 刷新索引。

开发

npm test
npm run pack:check

发布前：

npm pack --dry-run

确认软件包不包含 data/、*.sqlite 或私有知识库文件。

许可证

MIT