MCPVault reads Obsidian files directly, and its path checks are the security model

It talks to files, not to Obsidian

The architectural decision is up front: MCPVault works directly with vault files. It operates on .md, .markdown, .txt, .base and .canvas files in a local directory, and Obsidian does not need to be running.

No Obsidian plugin is required. That removes a whole class of trust question, because there is no code running inside the note-taking application to audit; the server is a separate process started by the MCP client.

The connection model is a local stdio process. The client launches MCPVault and passes the vault path as an argument, and the same set of tools is exposed to every client, so the server is not tied to one AI provider. Supported clients named in the README include Claude Desktop, Claude Code, ChatGPT Desktop on Enterprise and above, OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1 and later, Cursor, Windsurf and Ontheia, plus anything else that speaks local stdio MCP.

One detail worth knowing early: if you omit the vault path, the server uses your current working directory as the vault root. That default is convenient and also the easiest way to hand a model write access to more than you intended.

The path checks are the actual safety story

The README describes the containment model plainly. Path checks block traversal, symlink escapes, dotfiles, .obsidian, .git and node_modules. Every operation is restricted to the configured vault root.

The symlink case is the one that matters most in practice. A vault can contain a symlink pointing anywhere on the filesystem, and a check that only rejects ../ sequences is trivially defeated by one. The stated blocking of symlink escapes suggests the resolution happens after following, not before.

Path arguments are trimmed before validation, which closes a different gap: a leading or trailing space that survives into the path can turn a rejected name into an accepted one after the filesystem normalises it.

Destructive operations take a second route. delete_note and move_file require matching confirmation paths, so a model cannot silently delete a note by guessing its name; it has to pass the same path twice and get it right.

Eighteen tools, grouped by what they actually do

The tool set is organised into families rather than listed flat. File operations are read_note, write_note, patch_note, delete_note, move_note and move_file. write_note supports overwrite, append and prepend modes, which covers most editing needs without a separate edit primitive.

Partial reads get their own tools: get_note_outline returns structure without the body, and read_note_lines reads a range. Directory and batch reads are list_directory and read_multiple_notes. For a large vault, these are the difference between pulling an entire notebook into context and pulling two notes.

Search is a single tool, search_notes, with multi-word matching and BM25 reranking. Metadata and tags are covered by get_frontmatter, update_frontmatter, get_notes_info, get_vault_stats, manage_tags and list_all_tags. Wiki links are handled by wiki_link, which resolves names and returns alternative paths when a name is ambiguous instead of picking one for you.

Search and batch tools return compact fields by default. Setting prettyPrint: true expands the output, which is the right move when debugging why a search missed something and the wrong move for routine use.

Frontmatter edits keep the formatting of fields they did not touch

MCPVault parses frontmatter as YAML through gray-matter and updates it through an AST-aware path rather than a text replace. Unchanged fields keep their original formatting.

This is the detail that decides whether you can use an assistant on a vault with hand-written YAML. A serializer round-trip through a plain YAML library will requote strings, rewrap long values and drop comments, so a single frontmatter edit can produce a large diff in a note whose content nobody touched. Over a few dozen edits that noise makes real changes impossible to review.

The dependencies are small and legible: @modelcontextprotocol/server, gray-matter, trash, yaml. The dependency list also includes trash and yaml. There is no database, no index file and no daemon, so nothing needs migrating when you upgrade.

Running it: npx, an MCP inspector, then a client entry

Node 20.0.0 or later is the runtime requirement, and the package is published to npm as @bitbonsai/mcpvault, currently at version 0.16.0 under an MIT licence.

Test the published package with the MCP inspector before wiring it into a client:

npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault

If that works, add it to a client. For Claude Desktop the config file is claude_desktop_config.json:

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

OpenCode uses a different shape, with a mcp object and a command array in ~/.config/opencode/opencode.json:

{
  "mcp": {
    "obsidian": {
      "type": "local",
      "command": ["npx", "@bitbonsai/mcpvault@latest", "/path/to/your/vault/"],
      "enabled": true
    }
  }
}

To verify the connection, ask the client to list the tools or read a note you know the contents of. Prompts such as listing files, reading a named note or creating one dated today are what the README suggests as a first exercise.

For development from a clone, the repository pins Node 24 in .nvmrc and npm 10.9.0 through packageManager, and npm start runs the TypeScript server through tsx.

Where it is the wrong tool

The vault root is the whole security boundary, and a vault is often much larger than the notes you meant to expose. Anything inside that directory is readable and writable by the model, including a notes folder that holds credentials or a journal you did not intend to share. If you need finer scoping than one directory, this server does not offer it.

It is also not an Obsidian integration. There is no plugin, no access to Obsidian's own features, and no graph view or query language beyond the tools listed. Anything that depends on Obsidian metadata beyond frontmatter and file structure is outside the design.

Versioning is also worth a note. The repository has no GitHub releases, so npm is the version history. At 0.16.0 with a 0.x version number, breaking changes across minor versions are possible, and the CHANGELOG.md is the file to read before upgrading.

The last push was on 2026-10-13 and the repository is not archived.

Editorial conclusion

Adopt MCPVault if you want an assistant editing your notes through file operations you can inspect, since its operations are confined to one directory and no Obsidian plugin has to be trusted. Do not adopt it if you keep credentials or unrelated personal files under the same vault root, because the vault root is the entire blast radius and the server can write anywhere inside it. First confirm the path argument you pass resolves to the vault and not its parent, since omitting it silently makes your current working directory the vault.

Frequently asked questions

Official sources

1. bitbonsai/mcpvault on GitHub
2. Issues
3. License: MIT
4. README