mcpvault
让 Claude、ChatGPT 等 AI 助手通过自然语言安全读写你的 Obsidian 笔记库
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
让 Claude、ChatGPT 等 AI 助手通过自然语言安全读写你的 Obsidian 笔记库
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
想象一下：你花了三年时间构建了一个庞大的 Obsidian 知识库——上千篇笔记、复杂的标签体系、精心维护的 YAML frontmatter 区块。但每次想找点什么，只能靠记忆和手动搜索。某天你突然想：「要是能直接跟 AI 说'把最近添加的读书笔记归类到 #reading 标签下'，那该多好？」MCPVault 正是来解决这个问题的。
MCPVault 是一个基于 Model Context Protocol（MCP）标准的开源 MCP Server，由独立开发者 BitBonsai 构建维护。它充当 AI 助手与 Obsidian 笔记库之间的通用桥梁——无论你用的是 Claude Desktop、Claude Code、ChatGPT Desktop 还是未来支持 MCP 的任何 AI 工具，都可以借助 MCPVault 安全地读写你的 Obsidian 笔记。
Obsidian 作为最受青睐的个人知识管理工具（PKM）之一，其核心价值在于通过双链笔记和标签系统构建个人知识图谱。然而，随着笔记数量增长，手动维护成本急剧上升。与此同时，AI 助手的能力在 2024-2025 年间飞速进化，但大多数 AI 助手与本地知识库的连接仍然割裂——要么需要复杂的脚本配置，要么存在安全风险（如直接文件访问可能损坏 YAML frontmatter）。
MCP（Model Context Protocol）是由 Anthropic 主导推出的开放标准，旨在为 AI 助手与各类数据源建立统一的通信协议。MCPVault 的作者敏锐地抓住这一趋势，将 Obsidian 笔记库接入 MCP 生态，实现了「用一个标准，连接所有 AI」的愿景。
MCPVault 的架构体现了清晰的服务分层设计：
服务端入口（server.ts）：注册全部 15 个 MCP 工具，处理 CLI 参数（vault 路径、版本信息），协调各服务模块。所有文件操作均通过 FileSystemService 执行，并通过 PathFilter 进行安全校验。
文件系统服务（src/filesystem.ts）：封装所有文件读写操作。使用 Node.js 原生 fs/promises 模块，提供笔记读写、批量读取、移动、删除等能力。路径始终相对于 vault 根目录，自动处理前导斜杠和空白字符。
安全路径过滤器（src/pathfilter.ts）：MCPVault 的安全核心。明确禁止访问 .obsidian/（Obsidian 配置目录）、.git/（版本控制）、node_modules/（依赖）以及所有以点开头的隐藏文件。即使 AI 助手被诱导执行路径遍历攻击，PathFilter 也能在路径解析前将其拦截。
Frontmatter 处理器（src/frontmatter.ts）：使用 gray-matter 库解析 YAML frontmatter。这是 MCPVault 区别于直接文件操作的关键——它能精确区分笔记正文内容和元数据区块，防止 AI 在修改内容时意外破坏 YAML 结构。处理器还验证 YAML 块的结构，拒绝写入函数、符号等无效内容。
搜索服务（src/search.ts）：基于内容与 frontmatter 的全文搜索，支持多关键词匹配，并使用 BM25 算法对结果进行相关性重排序。搜索结果采用最小化字段命名（p、t、ex、mc 等），减少 token 消耗，最多返回 20 条结果。
MCPVault 提供 15 个 MCP 标准工具，覆盖笔记管理的全生命周期：
| 工具 | 功能 |
|---|---|
read_note | 读取单篇笔记（包含 frontmatter） |
write_note | 创建或覆盖笔记（支持追加、前置、覆盖三种模式） |
patch_note | 通过字符串替换进行局部更新 |
list_directory | 列出 vault 中的文件与目录 |
delete_note | 删除笔记（需提供路径确认） |
search_notes | 跨笔记全文搜索 |
move_note | 移动或重命名笔记 |
move_file | 移动或重命名任意文件（二进制安全，仅文件） |
read_multiple_notes | 批量读取最多 10 篇笔记 |
update_frontmatter | 安全更新 YAML frontmatter |
get_notes_info | 获取笔记元数据（不含正文） |
get_frontmatter | 仅提取 frontmatter 内容 |
manage_tags | 添加、移除或列出标签 |
get_vault_stats | vault 统计（笔记数、文件夹数、总大小等） |
list_all_tags | 列出所有标签及其出现频次 |
这种细粒度的工具设计使得 AI 可以像人一样「理解」笔记结构，而不是简单地做字符串替换。
MCPVault 的部署极其简单——它是一个纯 CLI 工具，不需要 Docker、不需要 Web 服务器、甚至不需要全局安装。
前提条件：Node.js >= 20.0.0（推荐通过 nvm 管理）。
三步启动：
npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vaultclaude_desktop_config.json 中添加：{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@bitbonsai/mcpvault@latest", "/path/to/your/vault"]
}
}
}
MCPVault 还提供了 MCP Inspector 支持——一个可视化的调试界面，可以单独测试每个工具的输入输出，极大降低了调试成本。
从 package.json 可以看出项目采用纯 TypeScript 开发，依赖极为精简：
@modelcontextprotocol/sdk ^1.20.0（MCP 官方 SDK）gray-matter ^4.0.3（成熟的 frontmatter 处理库）yaml ^2.8.3（与 gray-matter 配合使用）trash ^10.1.1（安全删除，文件进入系统回收站而非永久删除）.test.ts 文件代码质量方面，TypeScript 严格类型检查、详尽的单元测试覆盖、以及模块化的服务设计，使其在同类型开源项目中属于较高水准。文档质量极高——README 超过 25,000 字符，包含多客户端配置示例、安全设计说明、以及完整的工具 API 文档。
尽管 MCPVault 设计优秀，但仍有一些局限值得注意：
无原生 Web UI：纯 CLI 工具，不提供浏览器界面。对于不熟悉终端的用户有一定门槛。但这也是其保持轻量的代价——整个包仅 50MB 运行时依赖。
npx 冷启动延迟：每次 Claude Desktop 启动 MCPVault 时都需要通过 npx 下载/解压，第二次运行会使用本地缓存。但首次配置仍有等待时间。
Obsidian URI 局限性：项目还提供 Obsidian URI 生成能力（obsidian:// 链接），但 Obsidian URI 协议本身在非 macOS 平台支持有限，跨平台一致性需要额外配置。
YAML frontmatter 的复杂性：gray-matter 虽然成熟，但 Obsidian 社区的 frontmatter 用法五花八门（嵌入模板、Dataview 语法、Templater 指令等），复杂的 frontmatter 结构可能导致解析冲突。
MCPVault 的出现代表了一个重要趋势：AI 与本地知识库的深度集成。随着 Claude Code、Cursor IDE、Windsurf IDE 等 AI 编程工具的崛起，开发者们越来越希望 AI 能「看到」并「修改」自己的笔记、项目文档、甚至设计稿。MCP 作为开放标准正在快速成为这种连接的「USB 接口」。
从生态角度看，MCPVault 属于 MCP 生态中的「数据源连接器」类型——类比于 LangChain 的 Tool，但更专注于 Obsidian 这一单一场景的深度集成。这种专注反而使其在该场景下比通用方案更加可靠。
作者 BitBonsai 作为独立开发者，以 MIT 协议开源项目，并通过 GitHub Sponsors 和 Ko-Fi 接受赞助维护。项目保持着活跃更新（最新版本 0.11.2，持续迭代中），社区反馈积极。
MCPVault 是一款定位精准、设计精良的 MCP Server，为 Obsidian 用户提供了「用自然语言管理知识库」的桥梁。它以极简的依赖、清晰的架构、完善的工具集，在 AI 助手与个人知识管理之间架起了一条可靠通道。如果你已经在使用 Obsidian，并希望让 Claude、ChatGPT 等 AI 工具真正「读懂」并「整理」你的笔记，MCPVault 是目前最值得一试的解决方案。