MCPVault

A universal AI bridge for Obsidian vaults using the Model Context Protocol (MCP) standard. Connect any MCP-compatible AI assistant to your knowledge base - works with Claude, ChatGPT, and future AI tools. This server provides safe read/write access to your notes while preventing YAML frontmatter corruption.

https://mcpvault.org

Changelog

</div> <div align="center">

</div>

Universal Compatibility

Works with any MCP-compatible AI assistant including Claude Desktop, Claude Code, ChatGPT Desktop (Enterprise+), OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1+, Cursor IDE, Windsurf IDE, Ontheia, and future AI platforms that adopt the MCP standard.

https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c

Quick Start (5 minutes)

Install Node.js runtime:

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

Test the server:

If using the published package:

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

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.

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"

Success indicators: Your AI should be able to list files and read notes from your vault.

Why MCPVault?

Universal AI Compatibility

Built on the open Model Context Protocol standard, MCPVault is not locked to any single AI provider. As more AI assistants adopt MCP, your investment in this tool grows more valuable. Today it works with Claude and ChatGPT - tomorrow it will work with whatever AI tools emerge.

Future-Proof Your Knowledge Base

Instead of waiting for each AI company to build Obsidian integrations, MCPVault provides a universal adapter that works with any MCP-compatible assistant. One tool, endless possibilities.

Open Standard, No Lock-in

MCP is an open protocol. You're not tied to any specific vendor or platform. Your notes remain yours, accessible through any compatible AI assistant.

Features

✅ Safe frontmatter parsing and validation using gray-matter with AST-aware updates that preserve raw formatting for unmodified fields
✅ Path filtering to exclude .obsidian directory and other system files
✅ Complete MCP toolkit: 18 tools covering all vault operations
- File operations: read_note, write_note, patch_note, delete_note, move_note, move_file
- Partial reads: get_note_outline (headings without loading the full file), read_note_lines (a specific line range)
- Directory operations: list_directory
- Batch operations: read_multiple_notes
- Search: search_notes with multi-word matching and BM25 relevance reranking
- Metadata: get_frontmatter, update_frontmatter, get_notes_info, get_vault_stats
- Tag management: manage_tags (add, remove, list), list_all_tags
- Wiki links: wiki_link picks the shallowest match first (vault root before nested folders), then uses locale-aware path sorting at the same depth. Other matches are returned as alternatives; punctuation may sort before digits, so _Inbox can come before 00.projects.
✅ Write modes: overwrite, append, prepend for flexible content editing
✅ Tag management: add, remove, and list tags in notes
✅ Safe deletion with confirmation requirement to prevent accidents
✅ Automatic path trimming to handle whitespace in inputs
✅ TypeScript support with Node.js runtime (using tsx for execution)
✅ Comprehensive error handling and validation
✅ Token-optimized responses: 40-60% smaller responses with minified field names and compact JSON (v0.6.3+)
✅ Optional pretty-printing: Set prettyPrint: true for human-readable debugging
✅ Performance optimized: No unnecessary token consumption, efficient for large vaults
✅ Zero dependencies: No Obsidian plugins required, works with any vault structure

Prerequisites

Node.js runtime (v18.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 (Recommended)

No installation needed! Use npx to run directly:

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

Clone this repository
Use the correct Node.js version:

nvm use  # Uses Node 24 from .nvmrc

Install dependencies with npm:

npm install  # Corepack automatically uses npm 10.9.0

Test locally with MCP inspector:

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

Pro tip: Use MCP Inspector to test all server functionality before configuring with AI clients:

# 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 omitted from discovery and rejected if called directly.

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

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
Linux: ~/.config/Claude/claude_desktop_config.json

You can also access this through Claude Desktop → Settings → Developer → Edit Config

ChatGPT Desktop

Requirements: ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)

ChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:

Access ChatGPT developer mode (beta feature)
Configure MCP servers through the built-in MCP client
Create custom connectors for your organization

Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration.

Claude Code

Claude Code uses .claude.json configuration file:

User-scoped (recommended): Edit ~/.claude.json:

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

Project-scoped: Edit .claude.json in your project or add to the projects section:

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

Using Claude Code CLI:

claude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault

Goose Desktop

On Goose Desktop settings, click Add custom extension, and on the command field add:

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

Other MCP-Compatible Clients (2025)

Confirmed MCP Support:

IntelliJ IDEA 2025.1+ - Native MCP client support
Cursor IDE - Built-in MCP compatibility
Windsurf IDE - Full MCP integration
Ontheia - Self-hosted, open-source AI agent platform
Zed, Replit, Codeium, Sourcegraph - In development
Microsoft Copilot Studio - Native MCP support with one-click server connections

Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.

Examples

Ask your AI assistant about your notes:

"What files are in my Obsidian vault?"
"Read my note called 'project-ideas.md'"
"Show me all notes with 'AI' in the title"

Have your AI assistant help with note management:

"Create a new note called 'meeting-notes.md' with today's date in the frontmatter"
"Append tod

…

Obsidian

Installation

Configuration

How to use

README

MCPVault

Universal Compatibility

Quick Start (5 minutes)

Why MCPVault?

Universal AI Compatibility

Future-Proof Your Knowledge Base

Open Standard, No Lock-in

Features

Prerequisites

Installation

For End Users (Recommended)

For Developers

Usage

Running the Server

AI Client Configuration

Claude Desktop

ChatGPT Desktop

Claude Code

Goose Desktop

Other MCP-Compatible Clients (2025)

Examples

Ask your AI assistant about your notes:

Have your AI assistant help with note management:

You might also like