AI 能在你的 Vault 里做什么:obsidian-mcp-tools 的 16 个 MCP 工具逐一详解

原创2026-10-26 15:26:361,967 阅读

AI 能在你的 Vault 里做什么:obsidian-mcp-tools 的 16 个 MCP 工具逐一详解

obsidian-mcp-tools 是一个 Obsidian 插件,它自带一个本地 MCP 服务器,让 Claude Desktop 等 AI 应用通过 MCP(Model Context Protocol)协议安全地访问你的 Obsidian Vault:读笔记、语义搜索、执行 Templater 模板,全都只需说句话。这篇指南将逐一详解它内置的 16 个作用于 Vault 的 MCP 工具,并附上安装与避坑要点,帮助你快速把 AI 接入自己的笔记库。

一、obsidian-mcp-tools 是什么:插件 + 本地 MCP 服务器

理解这 16 个工具前,先花 30 秒搞清楚架构:

  • Obsidian 插件:安装在你的 Vault 里,负责管理服务器安装与配置,入口在插件设置页,见 SettingsTab.svelte;
  • 本地 MCP 服务器:一个签名的本地可执行文件,是 AI 应用与 Vault 之间的"安全桥梁"。AI 永远拿不到你的文件,只能调用服务器暴露的工具;
  • 两个协作组件:所有工具都通过 Local REST API 的 setupHandlers 中。

📌 一句话总结:AI 应用 → MCP 服务器(本地)→ Local REST API → 你的 Vault。全链路都在本机,服务器还使用了平台级凭据存储来保管 API Key。

整个工具调度基于一个统一的 ToolRegistry.ts 注册表实现,每个工具都有严格的参数校验(使用 ArkType Schema)。

前置要求清单

组件 是否必须 作用
Obsidian v1.7.7+ ✅ 必须 运行环境
MCP 客户端(如 Claude Desktop) ✅ 必须 AI 应用端
Local REST API 插件 ✅ 必须 提供本地 REST 接口与 API Key
Templater 插件 推荐 解锁 execute_template 等模板能力
Smart Connections 插件 推荐 解锁语义搜索 search_vault_smart

二、16 个 Vault MCP 工具逐一详解

先上一张总览表,后面的正文按同样顺序逐个展开。所有工具名与描述均来自 local-rest-api/index.ts、smart-connections/index.ts 与 templates/index.ts 的源码定义:

# 工具名 一句话功能 典型场景
1 get_active_file 读取当前打开的笔记 "总结一下我手头这篇笔记"
2 update_active_file 整体替换当前笔记内容 让 AI 重写全文
3 append_to_active_file 在末尾追加内容 追加会议纪要
4 patch_active_file 定位到某标题/块/字段处插入或修改 精确插入到指定章节
5 delete_active_file 删除当前笔记 ⚠️ 危险操作,慎用
6 show_file_in_obsidian 在 Obsidian 界面中打开某文件 让 AI 打开刚生成的笔记
7 list_vault_files 列出根目录或子目录文件 "看看我的 Projects 文件夹"
8 get_vault_file 读取任意笔记(Markdown/JSON) 按路径取原文
9 create_vault_file 新建或覆盖一篇笔记 让 AI 写一篇新日记
10 append_to_vault_file 向指定笔记末尾追加 给日志文件补一条记录
11 patch_vault_file 在指定位置修改某篇笔记 更新某一小节
12 delete_vault_file 删除指定笔记 ⚠️ 危险操作,慎用
13 search_vault 用 Dataview 或 JsonLogic 查询 查"所有带 #待办 标签的笔记"
14 search_vault_simple 全文关键词搜索 找某句话出现在哪些笔记
15 search_vault_smart 语义搜索(基于 Smart Connections) "找和我投资习惯相关的笔记"
16 execute_template 带参数执行 Templater 模板 一句话生成周计划

1. get_active_file:读取当前打开的笔记

最常用的一对一工具:返回 Obsidian 当前激活文件的内容,支持 Markdown 原文或含标签与 frontmatter 的 JSON 两种格式。定义见 local-rest-api/index.ts#L24-L49。适合"我正在读这篇,帮我翻译/总结/列要点"这类对话。

2. update_active_file:整体替换当前笔记

用传入的 content 完整覆盖当前笔记(源码对应 PUT /active/,见 index.ts#L52-L68)。⚠️ 注意是"覆盖"而非"追加",让 AI 重写全文前建议先自己备份。

3. append_to_active_file:末尾追加内容

安全系数最高的写入方式——只在当前笔记末尾追加,不动原有内容。适合让 AI 把访谈结论、TODO 直接补在你正在写的笔记后面。

4. patch_active_file:精准定位修改

这是最"聪明"的写入工具:可以相对某个标题、块引用(block reference)或 frontmatter 字段来插入或修改内容,目标不存在时还能自动创建(Create-Target-If-Missing)。实现细节见 index.ts#L90-L131。典型指令:"把这段话加到『计划』标题下面"。

5. delete_active_file:删除当前笔记

删除当前打开的文件,不可恢复(除非你的 Vault 有版本管理)。建议明确告诉 AI"不要主动删除文件"。

6. show_file_in_obsidian:在界面里打开文件

打开(不存在则新建)一篇笔记,可选 newLeaf 参数在新标签页打开。这个工具让 AI 能"把成果递到你眼前"——生成完周报后直接跳转到对应笔记,体验很顺。

7. list_vault_files:浏览目录结构

列出 Vault 根目录或任意子目录下的文件与文件夹,是 AI 做"知识盘点"的起点:"先列一下我的文件夹,再告诉我哪块最乱"。

8. get_vault_file:按路径读取任意笔记

与 get_active_file 相对,它按文件名取内容,同样支持 Markdown/JSON 双格式。AI 在搜索到目标后,会用它取全文做深度处理。

9. create_vault_file:创建新笔记

指定文件名与内容即可新建笔记,文件已存在时会更新覆盖。这是让 AI"把想法沉淀成笔记"的核心工具:对话内容一键归档进 Vault。

10. append_to_vault_file:向指定笔记追加

append_to_active_file 的"任意文件版",不需要该文件当前处于打开状态。配合日期命名的日志笔记,可以实现"每天一句话,自动追加到今天的日记"。

11. patch_vault_file:对任意笔记做定位修改

patch_active_file 的泛化版本:对任意指定文件,相对标题/块/frontmatter 字段插入或修改。两个 patch 工具是精确编辑的利器,比整体覆盖安全得多。

12. delete_vault_file:按路径删除笔记

按文件名删除,同样是高危操作,使用建议与 delete_active_file 相同。

13. search_vault:结构化查询(Dataview / JsonLogic)

这是"查询能力"的重头戏:支持两种查询语言——Dataview DQL(如果你装过 Dataview 插件就会写)和 JsonLogic 表达式,由 Local REST API 在服务端执行。比如"列出 2024 年创建且带 #idea 标签的笔记"这类组合条件,它都能查。实现见 index.ts#L178-L208。

14. search_vault_simple:关键词全文搜索

最简单的搜索:输入文字,返回匹配的文档片段,contextLength 参数可控制上下文长度。不知道用什么高级查询时,它是最稳的兜底选择。

15. search_vault_smart:语义搜索(本插件招牌能力)

前面几个搜索都靠"字面匹配",而 search_vault_smart 靠语义:基于 Smart Connections 插件的向量索引,理解"意思相近"的笔记。它还支持过滤器——folders / excludeFolders 指定包含或排除的文件夹、limit 限制结果数量,参数定义见 smart-connections/index.ts#L5-L38。这是把笔记库"喂"给 AI 最自然的方式:不记关键词也能找到当年的思考。

16. execute_template:一句话执行 Templater 模板

最后一个工具连接的是 Templater 插件:AI 传入模板名和参数,服务器通过 Local REST API 的 /templates/execute 端点真正执行模板,可选 createFile / targetPath 决定结果写入哪个文件,定义见 templates/index.ts#L10-L67。

💡 进阶玩法:模板参数用 <% tp.mcpTools.prompt("name", "description") %> 标签声明,服务器会自动解析出参数名和描述(解析逻辑在 parseTemplateParameters.ts#L32-L74),AI 就知道该传什么——模板即接口,非常优雅。

番外:还有 2 个辅助工具 + Prompts 能力

除 16 个 Vault 工具外,服务器还注册了两个辅助工具:

  • fetch:读取任意网页并转成 Markdown 返回,支持分页与原始 HTML,实现见 fetch/index.ts#L8-L24。虽然不直接操作 Vault,但"读网页 + 存进 Vault"是高频组合;
  • get_server_info:检查 Local REST API 状态与认证情况,排查连接问题的第一步。

此外服务器还实现了 MCP 的 Prompts 能力(不是工具,是提示词模板):Vault 里的 Prompts 文件夹中,凡是带 mcp-tools-prompt 标签的 Markdown 文件都会自动成为可调用提示词,客户端按名称取用并自动校验参数,逻辑在 prompts/index.ts#L24-L134,需求设计文档见 prompt-requirements.md。

三、快速上手:三步完成 MCP 服务器安装

  1. 装好前置插件:Community Plugins 里安装并启用 Local REST API(必须),按需安装 Templater、Smart Connections(推荐);
  2. 安装本插件:在 Community Plugins 搜索安装 obsidian-mcp-tools 并启用,进入插件设置点击 Install Server。插件会自动识别你的平台与架构(见 install.ts#L12-L36)、下载对应二进制、读取 Local REST API 的 API Key 并写好 Claude Desktop 配置——你只需授予一次明确许可;
  3. 重启 Claude Desktop 验证:对话中问"列出我的 Vault 根目录文件",能正常返回即打通。

服务器二进制默认安装在 Vault 的 .obsidian/plugins/obsidian-mcp-tools/bin/ 下。完整安装流程文档见 mcp-server-install.md,服务器说明见 packages/mcp-server/README.md。

出了问题看这里

  • 在插件设置页点 Open Logs 查看日志(macOS: ~/Library/Logs/obsidian-mcp-tools;Linux: ~/.local/share/obsidian-mcp-tools/logs);
  • 服务器不启动:确认 Claude Desktop 正在运行;
  • 连接错误:确认 Local REST API 插件已启用且 API Key 正确;
  • 权限错误:尝试重新安装服务器。

四、安全与隐私须知

  • AI 应用从不直接触碰你的 Vault 文件,一切经由本地 MCP 服务器 + Local REST API,通信加密、权限最小化;
  • API Key 使用平台级凭据存储保管,二进制带 SLSA 来源证明(L3 级可复现构建 + 签名),可验证未被篡改;
  • 使用 Claude Desktop 时,对话默认不会用于训练 Anthropic 的模型;
  • 漏洞请通过 SECURITY.md 描述的渠道私下报告。

五、常见问题

不装 Templater / Smart Connections 会影响哪些工具? 不装 Templater 则 execute_template 不可用;不装 Smart Connections 则只有 search_vault / search_vault_simple 两种搜索。其余 13 个工具不受影响。

整个过程需要联网吗? 服务器本身完全本地运行;网络请求只发生在 AI 应用与其模型之间。fetch 工具访问网页时需要网络。

如何深入了解源码结构? 项目采用 Monorepo + 特性化架构,整体架构说明见 project-architecture.md,MCP 服务器核心在 packages/mcp-server/src/features/。


16 个工具看似琐碎,组合起来却是一条完整链路:找(4 种搜索)→ 读(2 种读取)→ 写(覆盖/追加/精准修改)→ 生成(模板/新笔记)→ 打开看结果。把 AI 真正变成"懂你笔记库"的助手,就从这个 MCP 插件开始。

登录后查看全文
obsidian-mcp-tools