seekstone

相同的查询、相同的已提交 vault、每种各运行 20 次、同一台机器——该对比覆盖 2026 年 6 月至 8 月：快照（日期见每份已提交的报告）——八个服务器 x 三种 vault 规模 的完整结果见下文，并可从 harness 完全复现。

什么是 Seekstone？

Seekstone 是一个 Obsidian MCP 服务器——它让 Claude（以及任何Model Context Protocol 客户端）直接读写你的 Obsidian vault。无需打开 Obsidian 应用、无需安装插件、没有任何数据离开你的机器。

它直接读磁盘读取你的 vault，而不是绕过 Obsidian 中的远方 REST API 插件；同时，它在进程内维护了一个热全文索引。实际差异有两点：

• 速度。关键字搜索热态时为 个位数毫秒，语义搜索 ~14 ms——比我们基所测的所有其他 Obsidian MCP 服务器快 ~440×，因为无需产生子进程、每次查询也没有 HTTP 往返。

• 上下文：一个宽泛的搜索，通过 REST 代理服务器可返回数以十兆计的 MB和上百万 token，通过 Seekstone 只需约 2 KB——最高 ~47,000× 的减载，并且 vault 越大，差距越大。

搜索有三种模式：全文检索（带排序，支持模糊与前缀匹配）、可选的 本地语义搜索（基于含义，借助一个\r\n小型端侧 embedding 模型——可选开启，一次性 ~30 MB 下载后运行时离线），以及结构化元数据查询——query_notes 支持按 frontmatter 属性（status、due、type、…）、标签、文件夹、修改时间和大小过滤；像"本周改过的草稿笔记有哪些？"这类问题，只需十几字节的回答，不需要"先搜索再逐个读取"。

Claude 可以在毫秒内搜索、读取你的整个笔记库，而不会在一次工具调用中烧掉大部分上下文窗口。

作为 npm 包发布为 seekstone——用 npx -y seekstone 安装。（以往发布为 obsidian-mcp-seekstone；该别名已弃用，但已有客户端*依然可继续工作。）

Related MCP server: mcp-obsidian-ek

为什么使用 Seekstone？数据说话。

大多数 Obsidian MCP 服务器：命中的每一条搜索结果都会返回完整的笔记内容。在宽泛查询中，可能这个内容兆字节级，你的 LLM 不得不在其中逐字处理——绝大多数无关紧要，大量根据 token 一次火花耗尽。

Seekstone 取而代之返回简短的、带排序的摘要（默认约 ~120 字符，每个查询可调）。我们把 Seekstone 与 7 个其他 Obsidian MCP 服务器进行基基准——总计 8 个服务器——分别测试了三种规模——1,000 / 5,000 / 10,000 条笔记（分别各运行 20 次）。下面的每个数字都是完全可复现的：这些 vault 已经放进仓库（数据来源 1911 公开版《大英百科全书》公共领域内容），你可以克隆后自己运行完全一样的基准。

测试三种规模的目的在于——不同架构是就在这里分分岔的——真实 vault 只会不断增长。

**搜索载荷——每次查询返回的字节数（上下文税；越小越好）

Seekstone 的载荷保持平坦（≈2 KB），无论 vault 多大都不变——这是因为它始终返回排序摘要——并且如今相当于对比过的所有服务器中的payload 最小一款，超过了 mcpvault 协议的三者。REST 代理的服务器每命中一条都返回完整的笔记正文，因此它随着库增长同步膨胀——mcp-obsidian 在 10k 条笔记时达 95 MB，在 20 次跑批下 每条宽泛查询（如 the capital of）平均每次调用 370 MB / 9780 万 token。在 10k 条时，这就是**~约 47,000× 的上下文税差距**。

搜索延迟——热状态均值，ms（越低越好）

每个竞品都会为每次查询生成一个子进程或发起 HTTP 往返请求，而且多数竞品的工作量会随笔记库规模增长而增加。Seekstone 维护的是一个热内存索引——没有 IPC、没有网络——所以即使在 10,000 条笔记下，关键词搜索也保持在 个位数毫秒 级别（语义模式会额外叠加大约固定的 ~8 ms 的向量嵌入与扫描开销）。而且差距会随规模扩大：从 1k 到 10k 条笔记，竞品变慢 5–10×，而 Seekstone 几乎不动。就连最快的替代方案——obsidian-mcp-rs，它每次查询都会重新扫描整个笔记库——在 10k 条笔记、热索引状态下仍慢 ~6×，而且 payload 是 3×；至于 REST 代理这一类实现，则慢 ~90–250×。

在我们的基准测试集合中，Seekstone 是所有笔记库规模下唯一能同时提供约~2KB payload 和个位数毫秒级关键词延迟的服务器——而且据我们所知，也是唯一一个发布了可复现基准测试的 Obsidian MCP 服务器。测试服务、合成笔记库和完整结果均已开源：请查看 benchmark-scaling.md 和 harness。克隆、运行、验证。

安装

选择最适合你的方式。

使用 AI 智能体？请粘贴这整段提示词

如果你使用 Claude Code、Cursor 或其他编码智能体，无需自己完成任何步骤——把这段提示词粘贴出去，智能体就会替你完成安装：

为当前编辑器安装 seekstone MCP 服务器。运行 npx -y seekstone init --client code --write（其他客户端请使用 desktop、cursor 或 vscode）。它会自动检测我的 Obsidian 笔记库；如果列出多个，请问我选择哪一个，然后用 --vault "<path>" 重新运行。把任何错误反馈给我，然后让我重新启动当前会话，以便 seekstone 工具生效。

seekstone init 是完全非交互式的——使用 --write 时它会验证笔记库，并一次性写好客户端配置（Claude Desktop 通过 claude mcp add，其他客户端通过带时间戳备份的追加式 JSON 补丁）。

方式〇——一键安装（Claude Desktop，无需终端）

1. 从 GitHub Releases 下载 seekstone.mcpb

2. 用 Claude Desktop 打开——在 Finder 中双击，或右键点击 → 打开方式 → Claude Desktop

3. 在提示时选择你的 Obsidian 笔记库文件夹

当 seekstone 出现在 Claude 的工具栏中时，即表示安装成功。无需编辑 JSON、无需终端、也无需 Node.js。

方式二——引导式安装（推荐命令行用户）

打开终端（macOS：按 Cmd+Space，输入“终端”，回车），然后运行：

npx -y seekstone init

当 Seestone 出现在 Claude 工具栏的 Plug 图标下时，即表示安装成功。

Seekstone 会读取 Obsidian 自己的笔记库注册表来检测你的笔记库，然后验证该笔记库，再输出一段粘贴即可的配置块，或直接改动 Claude Desktop：

# Auto-detect vault, print config to paste
npx -y seekstone init

# Auto-detect vault, patch Claude Desktop in place (with backup)
npx -y seekstone init --write

# Specify vault explicitly if you have multiple
npx -y seekstone init --vault "/path/to/vault"

# Auto-configure Claude Code in one step (auto-detects vault, runs claude mcp add)
npx -y seekstone init --client code --write

# Or just print the Claude Code command without running it
npx -y seekstone init --client code

方式三——手动配置（Claude Desktop）

在 clabder_desktop_config.json 中加入如下内容（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "seekstone": {
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

方式 4 — Claude Code

一条命令即可自动检测你的笔记库并配置 Claude Code：

npx -y seekstone init --client code --write

或者，如果你希望显式指定笔记库路径，可以手动配置：

claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone

方式 5——Cursor

一键： — 然后你需要把 Cursor 的 SEEKSTONE_VAULT 环境变量设置为你笔记库的绝对路径（该链接安装的是一个占位符）。

或者让 CLI 自动检测你的笔记库并写入 ~/.cursor/mcp.json（并保留备份）：

npx -y seekstone init --client cursor --write

也可以把它手动添加到 ~/.cursor/mcp.json（全局）或 /.cursor/mcp.json`（按项目）：

{
  "mcpServers": {
    "seekstone": {
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

方式 6 —— VS Code

一键： ——然后在 VS Code 打开服务器配置时，把 THE_SEHKTotal=VaUاللT 设置为你笔记库的绝对路径（该链接安装的是一个占位符）。

或者让 CLI 自动检测你的笔记库，并把工作区配置写在当前目录的 .vscode/mcp.json 中：

npx -y seekstone init --client vscode --write

也可以直接从终端添加它：

code --add-mcp '{"name":"seekstone","command":"npx","args":["-y","seekstone"],"env":{"SEEKSTONE_VAULT":"/absolute/path/to/your/vault"}}'

也可以把这段内容手动添加到 .vscode/mcp.json（工作区范围）或通过命令面板 → MCP: Open User Configuration（用户全局）。注意两个 VS Code 的个性：顶层键是 servers而不是 mcpServers，并且要求必须存在 "type":"stdio"：

{
  "servers": {
    "seekstone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "seekstone"],
      "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

需要 VS Code 1.102 或更高版本；seekstone 会出现在 Copilot 的 Agent 模式工具选择器中。

其他 MCP 客户端（Windsurf、Cline 等）

Seekinone 是一个标准 MCP stdio 服务器——任何 MCP 客户端都可以运行它。在你客户端的 MCP 配置中使用相同的 JSON 块（command: npx，args: ["-y", "seekstone"]，env 变量 SEEKSTONE_VAULT）。

安装完成后，请重启客户端。在启动时，Seekstone 会扫描笔记库、建立内存中的全文索引（数千条笔记只需几秒），并在你编辑时保持该索引实时命中。下面的 19 个工具随后即可供 Claude 使用。

需要 /Node.js/（https://nodejs.org）≥ 22 才能使用 CLI 相关指令。一键的 .mcpb 包则不要求任何外部依赖。

如果 Seekstone 帮你节省了上下文，请考虑为仓库 点 run ⭐（https://github.com/shaqmughal/seekstone）——这能帮助其他人找到它。

Claude 可以用你的笔记库做什么？

连接 Seekstone 之后，你可以向 Claude 这样提问：

• “搜索我所有笔记中关于[主题]的内容并给我一个摘要” —— 使用 search，返回排序后的摘录片段，而不是整篇文件

• “找出所有带有 #project 标签的笔记，并列出它们的标题” —— 使用 list_notes，加一个标签过滤

• “只读取我的[项目]笔记中的“决策”部分” —— 使用 read_note，加一个 section 选择，只把那一段放入上下文

• “哪些笔记链接到我的[主题]笔记？这个笔记又链接到哪些笔记？” —— 使用 get_backlinks 和 get_links 来遍历你的笔记图

• “把今天的站会记录追加到我的日记笔记中” —— 使用 append_periodic_note，还会根据你在笔记库配置中的日记路径自动解析（不需要 Obsidian 先打开）

• **“把这篇笔记中所有旧项目名都改成新项目名” ** —— 使用 replace_in_note，在写之前先给你看一天预std-run 预览

• “在[笔记]的底部加一个摘要 section” —— 使用 append_note，不会碰 frontmatter

• “把 /inbox 中的所有笔记移到 /archive/[年度]” —— 使用 move_note

• “把这篇笔记 frontmatter 中 status 字段改成 done” —— 使用 patch_frontmatter，保持字段顺序与引号风格

• “按标准模板创建一篇今天的会议笔记” —— 使用 create_note

Claude 不会一次看到你的整个笔记库——它只会按需搜索和读取，因此即使是大规模笔记库（10k+ 条笔记），也能保持在上下文预算之内。

工具

读取

写入

每个写入工具（append_note、patch_note、patch_frontmatter、replace_in_note、rename_heading、move_note、delete_note、append_periodic_note，以及带 overwite: true 的 create_note) 都支持可选的 比较并交换（compare-and-swap）：将 read_note 中获得的 contentHash 作为 prevHash 传入，如果笔记在底层发生更改，调用会干净地失败——合并编辑的责任交由调用方；不会静默丢弃并发编辑，也不会移动或删除你尚未见过内容。每个变更结果都会返回新的 contentHash，因此链式编辑无需重新读取。

Fast and complete。 Seekstone 是我们基准测试的 Obsidian MCP server 中唯一能将 list_tags、outline_note、get_backlinks 和 get_links 作为一等公民工具暴露出来的服务器。还有四个能力让你们突显：

• 本地语义搜索，完全进程内。 设置 SEEKSTONE_SEMATIC=1 后，search 获得 mode: "semantic" 和 "hybrid" —— 通过一个小型本构型、设备端嵌入模型进行基于含义的检索（一次性 npx -y seekstone fetch-modl 下载；运行中的服务器永远不触碰网络）。在我们已提交的 10k-note 基准 vault 中，描述式查询在 top 5 中命中正确笔记的比例为 70%，而关键词搜索为 30% (已提交的 evl)。除了我们基准测试的服务器外，没有任何其他服务器附带离线、零原生依赖的嵌入模型——我们也在同一个 golden set 上与候选方案做了头对头测量（已提交的比较）。obsidian-tc 的 Ollama-backed 语义搜索确实更准确（90% vs 我们的 TPR 72% overall hit@5 —— it 的 137M-参数模型 vs 我们仅有的 8M），但它为此付出了 12×更慢查询（165 ms vs 14 ms p50）、71× 更慢索引（26.5 min vs 22 s cold）、~6.7× payload（14.4 KB vs 一条查询的 15.3 KB?) 更准确，并且还需要您安装并运行第二个服务器。obsidian-mcp-pro 根本无法索引这个 10k-note 笔记 vault（其四 JSON 向量存储会在嵌入约 15 分钟后超过 JavaScript 的字符串限制）。权衡随后您自己选，这些数字均已提交。

• Periodic notes，直接来自 filesystem.。 get_periodic_note 和 append_periodic_note 通过读取您 vault 自身的 config（.obsidian/daily-notes.json 和 Periodic Notes 插件) 来解析日、七、月、季度、年笔记的路径——即使 Obsidian 关闭。Every REST-based 服务器只能在 Obsidian 运行时进行此操作。

• Byte-identical frontmatter, guaranteed。 patch_frontmatter 就地编辑 YAML——保留 key 顺序、引号风格和注释——并且写入安全性由 harness 逐字节证明。我们调研的其他服务器都没有提供此保证。

• Zero coupling. 无需 Obsidian 应用、无需 Local REST API 插件，也无需插件版本漂移。只需磁盘上的文件。

配置

工作原理

Seekstone 使用 fast-glob 遍历 vault，解析每条笔记的 frontmatter（字节感知，从而可以在写入时证明前后该 frontmatter 区域完全相同），并在内存中构建 MiniSearch 全文本索引。搜索返回短小的排序结果片段，而非整篇笔记——这种“片段而非文档”的设计正是它在 context 开销上的优势之源。一个跨平台文件监视器（chokidar）在您在 Obsidian 中编辑时保持索引最新。

写入设计上非常保守：append_note 绝不触碰 frontmatter，patch_frontmatter 也是原地编辑 YAML 文档而非重新序列化，从而保留 key 顺序、引号风格和注释。

它的设计目标是持续运行。每次提交都在 macOS、Linux 和 Windows CI 上测试，写入工具对 pathological (ReDoS) 输入进行了加固，遇到个别未处理的 rejection 会记录而不是崩溃——因此您长期运行的 MCP 会话能结果保它有 warm 索引，而不是对话中途掉出。

如需逐层阅读代码结构——包、服务器内部、端到端请求流以及适应测试 harness——请参见 docs/ARCHITECTURE.md。

安全与隐私

Seekstone 会读取——并且通过写入工具修改——本地磁盘上 SEEKSTONE_VAULT 下的文件。运行中的服务器不进行任何网络调用，并且不发送遥遇（包中唯一的网络路径是显式的 npx -y seekstone fetch-model 子命令，该命令是可选语义搜索模型的一次性下载并经过 SHA-256 校验，在启动服务前退出）。默认日志只包含元数据（笔记内容仅在 debug 级别出现）。除您配置的可选日志文件之外，vault 之外不会写入任何内容；在 SEEKSTOONE_SEMANTIC=1 时，vault 的嵌入式 embedding 还显示在 cache 目录 ~/.cache/seekstone 下（笔记的派生向量会被这些向量下）；绝不会发送到任何数据。

写安全契约

给予一个 AI 您可以写入自己笔记的权限，不应该只说“信任我们”。Seekstone 附带一份有名称、经过测试的契约，见 docs/WRITE-SAFET.md，以它们作为的八结保证，每一项都链接到执行它的代码和证明它的测试**，并且由 harness 安全性套件（CI 中每次提交和发布中的字节）验证。The guarantees: zero network, vault sandbox, body editing preserves frontmatter byte-identical，atomic write (no torn files)， create never clobber，restorable delete （.trash/）, optional compare-and-swap on every write tool, and configurable write scope / read-only mode. 这一套件同样运行在 Filesystem-直接可比服务器上进行 vitally ，具体对比表格在契约文档中。

常见问题解答

“我需要在 Obsidian 中打开”？ 不需要。Seekstone 直接读取磁盘上的 vault 目录。Obsidian 可以打开，也可以关闭。

我需要安装 Local REST API 插件吗？
不需要。Seekstone 完全绕过了它——这正是它最大只有 of 1,000 倍有效载荷的原因。不需要任何插件。

支持哪些 AI 客户端？
支持所有基于 stdio 的 Model Context Protocol（MCP）的客户端——Claude Desktop、Claude Code、Cursor、Windsurf、Continue 等。

---

在我的库（vault）上使用安全吗？ 除非你显式调用 Seekstone 的写入工具之一（上表所列九个：create_note、append_note、patch_note、patch_frontmatter、replace_in_note、move_note、rename_heading、delete_note、append_periodic_note），否则 Seekstone 绝不会修改任何文件。运行中的服务器不会发出任何网络请求（语义搜索的模型由显式的 fetch-model 子命令以带外方式获取一次）。库路径被沙箱隔离——没有任何工具能读取或写入库路径之外。你还可以进一步收紧限制：SEEKSTONE_READ_ONLY=1 会把写入工具从会话中完全移除；SEEKSTONE_WRITE_PATHS 则会把写入限制在你允许的文件夹（例如仅 journal/**）。这两项限制都在调度层强制生效，而不是逐个工具检查，因此不会有工具忘记检查。

在 Windows 上能正常工作吗？ 可以。Seekstone 已在 CI 中针对 macOS、Linux 和 Windows 每次提交进行测试。

它能处理多大规模的 Obsidian 库？ Seekstone 已针对包含数千条笔记的库做过性能剖析。在随附的 10,000 条笔记基准库中，冷索引构建耗时几十秒，进程 RSS 保持在约 ~100 MB 以下；而典型的个人库只需几秒即可完成索引。语义模式会在启动后于后台嵌入，在 10k 条笔记时约需 20 秒，之后按库缓存，因此重启后重新加载远不到 1 秒。

seekstone init 如何自动找到我的库？ 它读取 Obsidian 自己的库注册表（obsidian.json）——也就是 Obsidian 用来记录已知库的同一个文件。如果你只有一个库，它会自动选中；如果有多个，它会一一列出，并让你用 --vault 参数选择。

.mcpb 文件是什么？ MCP Bundle（一个自包含的 zip，内含服务器及其 manifest。安装：在 Finder 中双击（或右键 → 打开方式 → Claude Desktop）选择你的库，然后完成即。不需要终端或 Node.js。

贡献与开发

欢迎贡献。贡献指南见 CONTRIBUTING.md，或直接开始：

npm install                                          # install all workspace deps
npm test                                             # run all tests
npm run lint                                         # biome check
npm run build -w seekstone                           # tsup → dist/
npm run build:mcpb                                   # build seekstone.mcpb bundle

npx vitest run packages/server/src/tools/search.test.ts  # single test file
npx vitest run -t 'parses a typical frontmatter'         # single test by name
npx tsc -p packages/server/tsconfig.json --noEmit        # typecheck

仓库布局

请项目有真正的构建（tsup → dist/），并发布到 npm。harness 是通过 tsx 从源码运行的。发布自动化全部，docs/RELEASING.md。

测量 harness

The harness 存在的目的是为了复现上述促成 filesystem-direct 设计的 benchmark 数字。默认的复现路径（fs/seekstone 后端，与 "自带的合成" vault）不需要额外环境；只有基于 REST 的后端（rest、mcp-obsidian、obsidian-mcp-server）需要运行 Obsidian 并安装 Local REST API 插件。

export SEEKSTONE_VAULT="/absolute/path/to/your/vault"

npx tsx packages/harness/src/cli.ts profile --vault "$SEEKSTONE_VAULT"
npx tsx packages/harness/src/cli.ts bench \
  --queries packages/harness/queries/default.json \
  --stats reports/vault-stats.json
npx tsx packages/harness/src/cli.ts safety --vault "$SEEKSTONE_VAULT"

Harness 环境变量：SEEKSTONE_REST_API_KEY（来自 Local REST API 插件）和 SEEKSTONE_REST_URL（默认值为 https://127.0.0.1:27124）。

支持

Seekstone 是免费开源软件。如果它为你节省了上下文（以及金钱），你可以 请我喝一杯咖啡。

许可证

MIT © Shaq Mughal