AI 能在你的 Vault 里做什么:obsidian-mcp-tools 的 16 个 MCP 工具逐一详解
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 服务器安装
- 装好前置插件:Community Plugins 里安装并启用 Local REST API(必须),按需安装 Templater、Smart Connections(推荐);
- 安装本插件:在 Community Plugins 搜索安装 obsidian-mcp-tools 并启用,进入插件设置点击 Install Server。插件会自动识别你的平台与架构(见 install.ts#L12-L36)、下载对应二进制、读取 Local REST API 的 API Key 并写好 Claude Desktop 配置——你只需授予一次明确许可;
- 重启 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 插件开始。