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:

   # Download from https://nodejs.org (v20.0.0 or later)
   # or use a package manager like nvm, brew, apt, etc.
   

2. Test the server:

   If using the published package:

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

3. Configure your AI client:

   Claude Desktop - Copy this to claude_desktop_config.json:

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

   Claude Code - Copy this to ~/.claude.json:

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

   OpenCode - Copy this to ~/.config/opencode/opencode.json

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

   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:

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

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:

nvm use  # Uses Node 24 from .nvmrc

3. Install dependencies with npm:

npm install  # Corepack automatically uses npm 10.9.0

4. Test locally with MCP inspector:

npx @modelcontextprotocol/inspector npm start /path/to/your/vault

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

# Install globally for easier access
npm install -g @modelcontextprotocol/inspector

# Test with any vault
mcp-inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault

Usage

Running the Server

End users:

npx @bitbonsai/mcpvault@latest
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
npx @bitbonsai/mcpvault@latest ./Vault

Developers:

npm start
npm start /path/to/your/obsidian/vault
npm start ./Vault

AI Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

Single Vault:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

Multiple Vaults:

{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/PersonalVault"
      ]
    },
    "obsidian-work": {
      "command": "npx",
      "args": [
        "@bitbonsai/mcpvault@latest",
        "/Users/yourname/Documents/WorkVault"
      ]
    }
  }
}

Read-only mode:

Add --read-only after the vault path to expose only read tools. Mutating tools are omitt