second-brain-mcp

一个只读的 MCP 服务器，适用于任何 Obsidian 或纯 Markdown 仓库，检索协议由服务器强制执行，而不是在提示词中请求。

将它指向一个 Markdown 笔记文件夹，任何 MCP 客户端——Claude Code、Claude Desktop、Cursor 等——都可以通过四个受管工具查询该知识库。服务器在构造上无法写入，无法离开仓库目录，并且在达到硬性的页面读取预算后会切断会话。

为什么

个人知识库最终被焊死在单一工具上。笔记存放在 Obsidian 中，而能够使用这些笔记的 AI 助手却在别处，于是你只能复制粘贴。即便助手确实获得了文件访问权限，“请只读取你需要的内容”也只是一句礼貌请求，而非规则。

这个服务器修复了这两点：

• 一个连接器，所有应用通用。 MCP 就是 AI 工具界的 USB-C——只需编写一次仓库连接器，任何 MCP 客户端都能使用它。

• 协议即法律，而非建议。 索引优先检索、硬性页面读取预算、只读访问和路径沙箱均在代码中强制执行。存在的操作只有这些受管控的操作。

Related MCP server: obsidian_mcp

安装

需要 Node.js 18 或更高版本。

选项 A - 通过 npm 安装

claude mcp add second-brain -- npx -y @nanthansr/second-brain-mcp /abs/path/to/your/vault

这一条命令即可将服务器注册到 Claude Code；npx 会自动获取并运行该软件包。其他客户端请参阅下面的配置块。

选项 B - 从源码安装

git clone https://github.com/nanthansr/second-brain-mcp
cd second-brain-mcp
npm install && npm run build
npm test   # 15-check integration suite - should end with SMOKE PASS
claude mcp add second-brain -- node /abs/path/to/second-brain-mcp/dist/index.js /abs/path/to/your/vault

Claude Desktop

添加到 claude_desktop_config.json（设置 → 开发者 → 编辑配置）：

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "@nanthansr/second-brain-mcp", "/abs/path/to/your/vault"]
    }
  }
}

Cursor

将相同的配置块添加到 ~/.cursor/mcp.json（或 Cursor 设置 → MCP → 添加新服务器）。

手边没有仓库？

完全省略仓库参数，服务器就会提供其自带的虚构演示仓库（“Alex Rivera”）——适合在 30 秒内快速试用：

claude mcp add second-brain-demo -- npx -y @nanthansr/second-brain-mcp

指向你的 Obsidian 仓库

你的仓库就是一个文件夹——就是 Obsidian 提示“将文件夹作为仓库打开”时你选择的那一个。将该文件夹的绝对路径作为参数传入：

注意：

• index.md 位于仓库根目录 可解锁索引优先流程（get_index）：一个每篇笔记占一行的目录页。如果你没有它，一切仍能正常工作——模型会回退到 search_notes。

• Obsidian 自身的配置（.obsidian/）以及任何其他点文件夹对服务器都是不可见的。

• 服务器从不修改任何内容——运行期间 Obsidian 可以保持打开。

用法

连接后，直接提问即可。典型流程（来自一次对演示仓库的真实会话）：

“Alex Rivera 正在做什么？Sam 是谁？” → get_index → read_note ×3（每次都会标注 read 1/5、read 2/5、read 3/5）→ 带引用的回答。

“这周我的仓库里有什么变化？” → list_recent(days: 7) → 按日期排列的列表，最新的在前。

“我把关于定价的笔记放在哪里了？” → search_notes(query: "pricing") → 匹配的页面及带行号的摘录，不消耗预算。

支持 MCP 提示（prompt）的客户端还可获得 vault-retrieval——一个斜杠命令模板，针对给定问题将模型固定到索引优先协议。

客户端获得的能力

预期流程模仿了一个细心的人使用 Wiki 的方式：先读目录，打开相关的一两页，然后带引用作答。定位成本低；读取有预算限制。

配置

安全模型

• 构造上只读。 代码库中不存在任何写入、编辑或删除工具。

• 路径沙箱。 每个路径都会先用 path.resolve 进行规范化，然后对照仓库根目录检查——拒绝目录穿越尝试（../…）。只有 .md 文件可读。

• 硬性页面预算。 在 N 次 read_note 调用（默认 5 次）之后，服务器会拒绝进一步读取，并告诉模型根据已有内容进行综合。失败的读取不消耗预算。

• 大小上限。 笔记截断为 50KB；搜索结果和最近列表也设有上限。

• 点文件夹会被跳过。 .obsidian、.git 及其他点文件夹均不可见。

• 代码公开，数据不公开。 该仓库只包含服务器代码和一个虚构的演示仓库。你的真实仓库就是运行时挂载的任何文件夹；它永远不会离开你的机器。

常见问题

我的数据会离开我的机器吗？ 不会。服务器作为 MCP 客户端的子进程在本地运行，从磁盘读取文件。它不包含任何网络代码。

它能修改或删除我的笔记吗？ 不能。不存在任何写入工具。这是代码本身的特性，而非某项设置。

当模型达到预算上限时会发生什么？ 第 6 次读取会返回一个错误，告诉模型根据已有的页面进行综合。新的对话拥有全新的预算。

为什么演示回答提到“Alex Rivera”？ 因为你正在使用内置的虚构演示仓库。请将你自己的仓库路径作为第一个参数传入。

开发

npm run build   # tsc -> dist/
npm test        # build + 15-check smoke test (spawns the real server over stdio)

冒烟测试使用 SDK 自带的客户端对接编译后的服务器——真实协议，无任何模拟。它验证了全部四个工具、资源、提示、路径穿越拒绝，以及读取预算会拒绝第 N+1 次读取。CI 在 Linux 和 Windows 上、Node 20 和 22 下运行它。

好奇为什么这样构建？请参阅 docs/design-notes.md——传输层、MCP 的三种原语、模式即提示（schemas-as-prompts），以及沙箱和预算决策。

路线图

• 远程变体（可流式 HTTP），让仓库可从托管客户端访问，并带身份验证

• 可选的按文件夹范围限制（只提供 wiki/，隐藏 journal/）

贡献

欢迎提交 Issue 和 PR。请保持这些不变式：没有写入工具，没有网络调用，冒烟测试保持通过且不被削弱。

许可证

MIT · 变更记录见 CHANGELOG.md