适合谁
- 希望通过多个 MCP 客户端访问本地 Obsidian vault 的用户。
- 需要保留未修改 frontmatter 原始格式的笔记工作流。
- 需要本地文件操作、搜索和标签管理的知识库用户。
M
60FMRS · C
MCPVault 是 MIT 许可的开源 MCP 服务器，面向本地 Obsidian vault，提供覆盖较完整的笔记和文件管理工具。其主要优点是 frontmatter 保护、路径安全、确认式危险操作和 stdio 隔离；主要风险是 AI 获得 vault 内容及写入权限后可能造成数据泄露或修改。
MCPVault 是一个轻量级 MCP 服务器，为 Obsidian vault 提供安全的读写访问。它支持笔记、目录、搜索、批量读取、元数据和标签管理，并通过路径校验、文件过滤及 YAML frontmatter 验证降低误操作风险。服务器运行在指定 vault 根目录内，使用 stdio 传输。
工具能力
read_note
读取笔记并解析 frontmatter。
write_note
以覆盖、追加或前置模式写入笔记。
patch_note
替换笔记中的精确字符串。
delete_note
删除笔记；需要路径确认，并支持永久删除或移入 vault/系统回收站。
move_note
移动或重命名笔记。
move_file
以二进制安全方式移动或重命名文件；需要确认源路径和目标路径。
list_directory
列出 vault 中的文件和目录，并过滤系统路径。
read_multiple_notes
批量读取最多 10 个笔记。
search_notes
按内容或 frontmatter 搜索笔记，并进行多词匹配和 BM25 相关性排序。
get_frontmatter
仅提取笔记的 frontmatter。
update_frontmatter
更新笔记 frontmatter，同时保留正文。
get_notes_info
获取笔记的文件大小、修改时间和 frontmatter 状态等元数据。
get_vault_stats
获取 vault 的笔记数、文件夹数、总大小和最近修改项。
manage_tags
在 frontmatter 中添加、删除或列出标签，并检测内联标签。
安装接入
安装 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"]}}}
选型与风险
不适合谁
- 不使用 Obsidian vault 或不具备本地 vault 目录的用户。
- 需要远程网络服务、云端托管或非 MCP 接入方式的用户。
- 不希望 AI 访问或修改 vault 内容和结构的用户。
所需权限
- 需要 Node.js 18 或更高版本。
- 需要对指定 vault 目录的读取权限；写入、移动和删除操作还需要相应写权限。
- 服务器可访问允许的 .md、.markdown、.txt、.base 和 .canvas 文件。
- AI 助手可看到允许文件的内容、目录结构及部分文件元数据。
风险与副作用
- 服务器对安全边界内的允许文件提供完整读写能力，错误指令可能修改或删除笔记。
- vault 内容、结构和文件元数据会暴露给获得访问权限的 AI 对话。
- 永久删除模式可能无法恢复；应在写操作前备份 vault。
- 路径过滤不等于内容隔离，允许文件中的敏感内容仍可被读取。
常见排障
- 确认已安装 Node.js 18 或更高版本，并且 `npx` 可用。
- 确认传入的 vault 路径正确，且用户拥有相应读写权限。
- 确认所有路径均相对于 vault 根目录，不能通过路径遍历访问外部文件。
- 检查客户端配置文件位置和 JSON 语法，修改后重启客户端。
- 若 .obsidian 文件出现，检查客户端显示内容；服务器设计上会过滤 `.obsidian`、`.git`、`node_modules` 和系统文件。
使用场景
让 AI 列出、读取和搜索 Obsidian 笔记。
创建、追加、前置或精确修改笔记内容。
批量读取笔记并获取 vault 统计信息。
维护 frontmatter 和标签。
移动、重命名或在确认后删除笔记和文件。
支持客户端
Claude Desktop完整支持
Claude Code完整支持
OpenCode完整支持
Goose Desktop完整支持
ChatGPT Desktop部分支持
IntelliJ IDEA 2025.1+完整支持
Cursor IDE完整支持
Windsurf IDE完整支持
Ontheia完整支持
Microsoft Copilot Studio完整支持
OpenAI Codex完整支持