bitbonsai/mcpvault

A local MCP server that lets compatible clients read, search, and edit notes in an Obsidian vault. MCPVault works directly with vault files, restricts file operations to the configured vault root, and preserves formatting for unchanged frontmatter fields.
https://mcpvault.org
Changelog
Supported clients
Configuration examples are available for Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor, Windsurf, and Ontheia. Other clients can use MCPVault if they support local stdio MCP servers.
https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c
Quick start
1. **Install Node.js runtime:**
2. **Test the server:**
If using the published package:
3. **Configure your AI client:**
**Claude Desktop** - Copy this to claude_desktop_config.json:
**Claude Code** - Copy this to ~/.claude.json:
**OpenCode** - Copy this to ~/.config/opencode/opencode.json
Replace /path/to/your/vault with your actual Obsidian vault path.
For other platforms, see detailed configuration guides below.
4. **Test with your AI:**
- "List files in my Obsidian vault"
- "Read my note called 'project-ideas.md'"
- "Create a new note with today's date"
To verify the connection, ask your client to list MCPVault tools or read a known note.
How it connects
An MCP client starts MCPVault as a local stdio process and passes the vault path. MCPVault exposes the same tools to each supported client, so the server is not tied to one AI provider. Obsidian does not need to be running, and no Obsidian plugin is required.
Features
- AST-aware frontmatter updates preserve formatting for unchanged YAML fields.
- Path checks block traversal, symlink escapes, dotfiles, .obsidian, .git, and node_modules.
- Eighteen MCP tools cover note and file operations:
- File operations: read_note, write_note, patch_note, delete_note, move_note, move_file
- Partial reads: get_note_outline, read_note_lines
- Directory and batch reads: list_directory, read_multiple_notes
- Search: search_notes with multi-word matching and BM25 reranking
- Metadata and tags: get_frontmatter, update_frontmatter, get_notes_info, get_vault_stats, manage_tags, list_all_tags
- Wiki links: wiki_link resolves names and returns alternative paths when a name is ambiguous
- write_note supports overwrite, append, and prepend modes.
- delete_note and move_file require matching confirmation paths.
- Path arguments are trimmed before validation.
- Search and batch tools return compact fields by default; set prettyPrint: true for expanded output.
- The package exports TypeScript declarations and public types.
- MCPVault requires no Obsidian plugin.
Prerequisites
- Node.js runtime (v20.0.0 or later)
- An Obsidian vault (local directory with .md, .markdown, .txt, .base, or .canvas files)
- MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)
Installation
For end users
npx downloads and runs the package:
If you omit the vault path, the server uses your current working directory as the vault root.
For developers
1. Clone this repository
2. Use the correct Node.js version:
3. Install dependencies with npm:
4. Test locally with MCP inspector:
Use MCP Inspector to test the server before adding it to a client:
Usage
Running the Server
**End users:**
**Developers:**
AI Client Configuration
Claude Desktop
Add to your Claude Desktop configuration file:
**Single Vault:**
**Multiple Vaults:**
**Read-only mode:**
Add --read-only after the vault path to expose only read tools. Mutating tools are omitted from discovery and rejected if called directly.
The CLI also accepts --read-only true and --read-only=true for configuration systems that require explicit values. Omit the option, or set it to false, to keep normal read/write access.
**Configuration File Locations:**
- **macOS:** ~/Library/Application Support/Claude/claude_desktop_config.json
- **Windows:** C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json