Mcpvault

What @bitbonsai/mcpvault does

@bitbonsai/mcpvault gives MCP clients access to a local Obsidian vault. It can inspect, search, create, modify, rename, and remove notes, while also handling selected non-note files. The server operates against a configured vault root and keeps file operations within that root.

Obsidian does not need to be open, and no Obsidian plugin is required. Supported vault content includes .md, .markdown, .txt, .base, and .canvas files. Note-oriented operations remain limited to notes, while directory listing and file movement can include other filenames.

How it works

An MCP client launches the package as a local stdio process and passes the vault path as a command-line argument. If no path is supplied, the working directory becomes the vault root. Multiple vaults can be exposed by defining separate MCP server entries with different paths.

Path validation blocks traversal and symlink escapes, along with access to dotfiles, .obsidian, .git, and node_modules. Search and directory listing can also use repeated default exclusions, while per-call exclusions add further paths for that request. Direct read and write operations remain available for excluded paths.

The server supports read-only operation through the --read-only option. In that mode, mutating tools are omitted from discovery and rejected if called directly. Destructive deletion and binary-safe file moves require matching confirmation paths.

Setup and configuration

Install Node.js 22.12.0 or later and provide an Obsidian vault directory. End users can run the published package with:

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

Use the MCP Inspector to test the connection before adding it to a client:

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

For a local development checkout, install dependencies with npm and start the server using npm start, optionally followed by the vault path. Client configuration uses the npx command and passes @bitbonsai/mcpvault@latest plus the vault location. The server supports Claude Desktop, Claude Code, ChatGPT Desktop for Enterprise, Education, or Team accounts, OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1 or later, Cursor, Windsurf, and Ontheia when configured for local stdio MCP servers.

Tools and capabilities

• Read, create, append to, prepend, patch, delete, move, and rename notes with read_note, write_note, patch_note, delete_note, and move_note.
• Move any vault file with move_file, including binary files.
• Browse files and folders with list_directory, or read up to 10 notes in one batch with read_multiple_notes.
• Search note content and frontmatter with multi-word matching and BM25 reranking through search_notes.
• Inspect frontmatter, note metadata, vault totals, folders, size, and recent changes with get_frontmatter, get_notes_info, and get_vault_stats.
• Update YAML frontmatter without changing note content, and add, remove, or list tags with update_frontmatter and manage_tags.
• Discover tag usage across frontmatter and inline hashtags with list_all_tags.
• Resolve Obsidian wiki-link syntax with wiki_link, including display-text, escaped table, and path-qualified forms. Ambiguous basename matches include alternative paths.
• Navigate large notes using get_note_outline followed by read_note_lines, avoiding a full-note read when only a section is needed.

Limitations and notes

The server is local and file-based: the client process must be able to access the vault directory. Read and write tools operate on notes, while list_directory and move_file cover broader file types. Batch note reads are limited to 10 files. Search and batch responses use compact fields by default; callers can request expanded output with prettyPrint: true. Unchanged YAML frontmatter fields retain their formatting during AST-aware updates.