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.
$ npx -y skills add bitbonsai/mcpvault --agent claude-code
Repo: bitbonsai/mcpvault
What's inside
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.
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
Install Node.js runtime:
# Download from https://nodejs.org (v20.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:
To verify the connection, ask your client to list MCPVault tools or read a known note.
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.
.obsidian, .git, and node_modules.read_note, write_note, patch_note, delete_note, move_note, move_fileget_note_outline, read_note_lineslist_directory, read_multiple_notessearch_notes with multi-word matching and BM25 rerankingget_frontmatter, update_frontmatter, get_notes_info, get_vault_stats, manage_tags, list_all_tagswiki_link resolves names and returns alternative paths when a name is ambiguouswrite_note supports overwrite, append, and prepend modes.delete_note and move_file require matching confirmation paths.prettyPrint: true for expanded output..md, .markdown, .txt, .base, or .canvas files)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.
nvm use # Uses Node 24 from .nvmrc
npm install # Corepack automatically uses npm 10.9.0
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
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
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:
~/Library/Application Support/Claude/claude_desktop_config.jsonC:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonYou can also access this through Claude Desktop → Settings → Developer → Edit Config
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:
Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration.
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
On Goose Desktop settings, click Add custom extension, and on the command field add:
npx @bitbonsai/mcpvault@latest /path/to/your/vault
Confirmed MCP Support:
Most modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.
npm install -g @bitbonsai/mcpvault
View @bitbonsai’s profileA 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.
@bitbonsaiFAQ
bitbonsai-mcpvault-2 is a Claude Code plugin with 2 hand-picked skills for mcp servers work, indexed on Flowy. Install it with the command on its page. It includes obsidian, triage. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it