如何将 Claude Desktop 连接到 Obsidian——穿越 4 个 MCP 服务器的旅程

想象一下：你有 400 多篇 Obsidian 笔记，多年积累下来。所有内容散落在 vault 根目录，概念和技术笔记混杂在一起，存在重复（ideas.md 和一个包含 13 个文件的 ideas/ 文件夹），没有体系。你想整理它——建立合理的文件夹架构，添加 MOC 文件，整理标签。手动做既枯燥又耗时。合乎逻辑的想法：通过 MCP 将 Claude 连接到 Obsidian，让 AI 来做重构。结果发现——这是一条穿越雷区的路。以下是我为了找到可行方案所经历的一切。

什么是 MCP，为什么没那么简单

MCP（Model Context Protocol）是 Anthropic 推出的开放协议，允许 Claude 连接外部工具和数据。原理很简单：运行一个本地服务器，暴露"工具"（tools），Claude 在对话中调用它们。

理论上 Obsidian 有很多 MCP 服务器。实际上——每个都有自己的问题。

Obsidian 生态的核心问题：Obsidian 是一个没有官方 MCP 的封闭应用。社区填补了空白，但每个实现都各行其道，没有一个获得"官方认可"。

尝试 1：MarkusPfundstein/mcp-obsidian

搜索时找到的第一个工具。GitHub 上 3400 颗星，出现在每个教程中。看起来是个安全的选择。

工作原理：基于 Obsidian 中 Local REST API 插件的 Python 服务器。服务器通过 HTTPS 与插件通信，插件通过 Obsidian API 执行操作。

出了什么问题

• 17 个月未更新
• 85 个未解决的 issues
• 没有 move/rename——只有 read、write、append、delete
• Local REST API 有一个已记录的数据丢失 bug：POST 端点在 append 时可能会静默覆盖文件

不适合重构——我们需要移动文件并保留链接。继续寻找。

尝试 2：aaronsb/obsidian-mcp-plugin

找到一个作为 Obsidian 原生插件运行的方案。这意味着可以直接访问 Obsidian 的内部 API——backlinks、Dataview、链接图谱。通过原生 API 移动文件会自动更新所有 wiki 链接，因为 Obsidian 自身处理这一切。

安装困难

• 插件不在 Obsidian 官方目录中（PR 因验证错误而待审中）
• 必须通过 BRAT（Beta Reviewers Auto-update Tool）安装
• Claude Desktop 不直接通过 UI 接受 Bearer token——不得不在插件中启用 HTTPS
• localhost 的自签名证书产生信任问题

经过所有这些变通方案终于连接上了。基础测试——vault.move 确实会重写 [[wikilinks]]，按预期工作。

在实战中出了什么问题

当我开始大规模重构时（在 Obsidian 中拖放数十个文件夹 + 同时进行 MCP 操作），服务器卡住了 4 分钟以上。原因：插件在 Obsidian 内部运行。当 Obsidian 在大规模结构变更后重新索引数千个文件时，插件也随之阻塞。

结论：依赖于打开的 Obsidian 实例及其索引对批量操作是致命的。

尝试 3：@bitbonsai/mcpvault

按逻辑——我们需要一个不依赖 Obsidian 的服务器。直接处理磁盘上的文件。@bitbonsai/mcpvault——在很多评测中被推荐。直接文件系统访问，简单设置（npx @bitbonsai/mcpvault@latest /path/to/vault），14 个工具。甚至不需要打开 Obsidian。

在安装之前，我检查了一个关键问题——移动文件时 wiki 链接是否会更新。找到了一个用户评价：

文件系统连接器不知道自己在 Obsidian 中——它只看到一个包含 <code>.md</code> 文件的文件夹。不知道文件名承载语义权重，不知道每个 <code>[[wikilink]]</code> 在重命名或移动的瞬间就会断裂。自动更新链接只在从应用内部重命名时才有效。我在让 Claude 清理文件名后才发现这一点——回来时仪表板上一半的链接都断了。

在 mcpvault 自己的文档中得到证实：PR #101（wiki link resolution）在审查中，未合并。所以通过 mcpvault 移动会破坏一半的 vault。不适用。

尝试 4：VaultForge（最终方案）

blacksmithers/vaultforge——专门为做重构的 AI 代理构建。

架构正确

• 直接文件系统——不依赖 Obsidian
• 自有 wikilink 引擎——实现了 [[wikilink]] 解析逻辑，更新所有形式（stem、完整路径、alias、embed）
• 默认 dry run——所有破坏性操作先展示将要发生的变化，然后你确认
• 27 个工具对比竞品的 8–14 个：batch_rename、update_links、backlinks（影响分析）、prune_empty_dirs、frontmatter、smart_search（BM25）、vault_themes（TF-IDF clustering）
• MIT 许可证，TypeScript，零子依赖
• 30 秒安装——通过 .mcpb（Claude Desktop 的一键扩展）

在隔离文件上进行安全测试

创建了 4 个带有交叉链接的测试文件——stem 链接、带 alias 的链接、带完整路径的链接。将一个文件移到子文件夹：

delta.md → subfolder/delta-renamed.md

VaultForge 展示了 dry run："1 个文件将被重命名，3 个链接将被更新"。实际执行。

之后检查——三种链接类型全部正确更新。这正是所有之前工具所缺少的。

如何安装 VaultForge——最终指南

如果你使用 macOS 和 Claude Desktop：

步骤 1

下载 .mcpb 文件：

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb \
  -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

步骤 2

Claude Desktop 将打开扩展安装对话框。输入 vault 的绝对路径——不要使用反斜杠，使用正常空格：

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault

步骤 3

点击 Save。Claude Desktop 会自动将扩展添加到配置中。无需重启——.mcpb 扩展会自动检测。

步骤 4

验证：在新对话中询问："What is the status of my Obsidian vault?"——应返回类似 totalFiles: 416, totalDirs: 135, ... 的内容

我对 Obsidian MCP 生态系统的认识

第一，"最受欢迎"不等于"能用"。MarkusPfundstein/mcp-obsidian 有 3400 颗星，是默认推荐，但它已过时且缺少关键操作。

第二，原生插件有隐藏成本。aaronsb 插件看起来完美——graph、Dataview、原生 move。但依赖于运行中的 Obsidian 实例及其索引使其不适合严肃的批量操作。

第三，没有 link-engine 的直接文件系统是陷阱。Mcpvault 快速简单，但"只是移动文件"会破坏 vault 结构。链接承载着文件系统不了解的强制语义。没有自己的 wikilink 逻辑实现，工具就变成了地雷。

第四，在隔离数据上测试。在将大规模重构交给任何工具之前——创建一个包含 4–5 个带交叉链接文件的测试文件夹，看看会发生什么。5 分钟的测试可以节省数小时的备份恢复时间。

第五，保持 vault 的 git 备份。这是最重要的。在 vault 内部执行一次 git init 并定期提交——这是对 AI 代理或工具任何错误的保险。如果出了问题——git reset --hard 可以恢复一切。

结论

这段旅程花了几个小时，经历了三次失败的尝试。最终架构如下：

• VaultForge——主要工作工具。直接文件系统 + 自有 wikilink 引擎 + 27 个工具 = 任何规模的稳定重构。
• Git——vault 版本控制。对任何错误的免费回滚。

现在我可以做这一切的初衷了：让 Claude 将 400 篇笔记按照 PARA 架构整理，合并重复项，添加 frontmatter，构建 MOC 地图。每个操作都是安全的，链接被保留，dry run 在任何变更前展示将会发生什么。

如果你也在看着自己杂乱的 Obsidian 想要一个 AI 助手——直接从 VaultForge 开始。不要重复我走过的路——穿越死掉的项目、beta 插件和没有链接逻辑的文件系统服务器。