MCPVault

社区

安全连接 Obsidian 知识库的 MCP 桥梁

分类: 文件系统第 8 / 24
Stars: ★ 1.7k 非常热门
传输方式: stdio（本地进程）
运行环境: Node.js 18+
凭据: 无需凭据
许可证: MIT
最近提交: 18 天前
工具数: 14

60FMRS · C

MCPVault 是 MIT 许可的开源 MCP 服务器，面向本地 Obsidian vault，提供覆盖较完整的笔记和文件管理工具。其主要优点是 frontmatter 保护、路径安全、确认式危险操作和 stdio 隔离；主要风险是 AI 获得 vault 内容及写入权限后可能造成数据泄露或修改。

最强项 · 文档质量 15/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

13/20

维护活跃度

10/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: README 描述了 14 个工具、错误处理、路径校验和测试命令，正常路径看起来合理；但服务器清单未缓存，未提供源码、CI 或已提交测试证据，无法验证 MCP 初始化/工具列表握手、工具实现与边界错误。README 还同时声称“零依赖”并要求 npm 安装依赖，且使用 latest 增加可控性风险，因此扣分。
安全与权限 13/20: README 明确披露了 stdio 传输、限定 vault 根目录、路径遍历与符号链接检查、扩展名/目录过滤，以及删除和文件移动的确认参数，体现了较好的边界和副作用控制；但没有认证或调用方授权机制，AI 可读取和修改允许范围内的全部内容，且未提供源码验证这些控制，网络、权限和敏感数据暴露处理证据也有限，因此未接近满分。
维护活跃度 10/20: 仓库未归档，MIT 许可证明确，且存在维护者组织、变更日志链接和 13 个开放 issue；但提示材料没有可核查的发布/提交频率、CI、依赖更新、issue 响应或安全响应渠道证据，无法按持续维护标准给高分。
文档质量 15/20: README 覆盖运行时要求、安装、多个主流客户端配置、14 个 API 的示例参数与响应、限制、故障排查、安全考虑和测试命令，文档可用性较强；但没有源码或清单交叉验证，认证、权限模型、依赖/版本锁定、成本和部分平台声明缺少独立证据，且存在“零依赖”等表述不一致，因此扣分。
安装易用性 13/20: 从 Node.js 准备到 npx 启动、Inspector 验证和 Claude/其他客户端配置的路径清晰，步骤较少并提供多平台示例；但依赖 npx、网络获取 latest、客户端功能/订阅限制和本地权限，且没有真实 CI/测试覆盖来验证连接流程，所以不能超过静态校准上限并扣除不确定性分。

静态评测 · 未实际运行收录于 2026-07-29

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件写入 / 删除本地文件

适合谁

希望通过多个 MCP 客户端访问本地 Obsidian vault 的用户。
需要保留未修改 frontmatter 原始格式的笔记工作流。
需要本地文件操作、搜索和标签管理的知识库用户。

不适合谁

不使用 Obsidian vault 或不具备本地 vault 目录的用户。
需要远程网络服务、云端托管或非 MCP 接入方式的用户。
不希望 AI 访问或修改 vault 内容和结构的用户。

所需权限

需要 Node.js 18 或更高版本。
需要对指定 vault 目录的读取权限；写入、移动和删除操作还需要相应写权限。
服务器可访问允许的 .md、.markdown、.txt、.base 和 .canvas 文件。
AI 助手可看到允许文件的内容、目录结构及部分文件元数据。

风险与副作用

服务器对安全边界内的允许文件提供完整读写能力，错误指令可能修改或删除笔记。
vault 内容、结构和文件元数据会暴露给获得访问权限的 AI 对话。
永久删除模式可能无法恢复；应在写操作前备份 vault。
路径过滤不等于内容隔离，允许文件中的敏感内容仍可被读取。

安装接入

准备工作

运行环境：Node.js 18+

安装 Node.js 18 或更高版本。使用 npx 运行 npx @bitbonsai/mcpvault@latest /path/to/your/vault，并将提供的 JSON 配置加入支持的 MCP 客户端；将路径替换为实际 Obsidian vault 路径。也可以省略路径，此时使用当前工作目录。配置后重启客户端并测试列出文件或读取笔记。

claude_desktop_config.json

{"mcpServers":{"obsidian":{"command":"npx","args":["@bitbonsai/mcpvault@latest","/path/to/your/vault"]}}}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/path/to/your/vault"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add obsidian -- npx @bitbonsai/mcpvault@latest /path/to/your/vault

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

配置后询问 AI「列出我的 Obsidian vault 里的文件」，若能返回 vault 中的文件列表（工具列表中出现 read_note、write_note 等），即说明连接成功。

常见排障

确认已安装 Node.js 18 或更高版本，并且 `npx` 可用。
确认传入的 vault 路径正确，且用户拥有相应读写权限。
确认所有路径均相对于 vault 根目录，不能通过路径遍历访问外部文件。
检查客户端配置文件位置和 JSON 语法，修改后重启客户端。
若 .obsidian 文件出现，检查客户端显示内容；服务器设计上会过滤 `.obsidian`、`.git`、`node_modules` 和系统文件。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

列出我的 Obsidian vault 里的所有文件
读取我的笔记 project-ideas.md
在 daily-log.md 末尾追加今天的日记
给 research-notes.md 添加标签 machine-learning 和 ai

工具能力 14

read_note 只读

读取笔记并解析 frontmatter。

write_note 写入

以覆盖、追加或前置模式写入笔记。

patch_note 写入

替换笔记中的精确字符串。

delete_note 破坏性

删除笔记；需要路径确认，并支持永久删除或移入 vault/系统回收站。

move_note 写入

移动或重命名笔记。

move_file 写入

以二进制安全方式移动或重命名文件；需要确认源路径和目标路径。

list_directory 只读

列出 vault 中的文件和目录，并过滤系统路径。

read_multiple_notes 只读

批量读取最多 10 个笔记。

展开其余 6 个工具

search_notes 只读

按内容或 frontmatter 搜索笔记，并进行多词匹配和 BM25 相关性排序。

get_frontmatter 只读

仅提取笔记的 frontmatter。

update_frontmatter 写入

更新笔记 frontmatter，同时保留正文。

get_notes_info 只读

获取笔记的文件大小、修改时间和 frontmatter 状态等元数据。

get_vault_stats 只读

获取 vault 的笔记数、文件夹数、总大小和最近修改项。

manage_tags 写入

在 frontmatter 中添加、删除或列出标签，并检测内联标签。

使用场景

让 AI 列出、读取和搜索 Obsidian 笔记。

创建、追加、前置或精确修改笔记内容。

批量读取笔记并获取 vault 统计信息。

维护 frontmatter 和标签。

移动、重命名或在确认后删除笔记和文件。

支持客户端

Claude Desktop

Claude Code

OpenCode

Goose Desktop

ChatGPT部分支持

IntelliJ IDEA 2025.1+

Cursor

Windsurf IDE

Ontheia

Microsoft Copilot Studio

Codex

依据项目文档列出，未经本站实测。

详细介绍

MCPVault 是一个轻量级 MCP 服务器，为 Obsidian vault 提供安全的读写访问。它支持笔记、目录、搜索、批量读取、元数据和标签管理，并通过路径校验、文件过滤及 YAML frontmatter 验证降低误操作风险。服务器运行在指定 vault 根目录内，使用 stdio 传输。