@bitbonsai/mcpvault MCP-Server | PlugMCP
Zum Inhalt springen Verzeichnis Produkt Ressourcen Pricing Vom Herausgeber
Dokumentation
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
Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
Beliebiges Tool in beliebigen Agenten. MCP-Verzeichnis für Leute, die keine Server schreiben.
Produkt
Verzeichnis
Entwickler
Unternehmen
2026-11-16
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.
Quick start
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:
"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
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
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 npx @bitbonsai/mcpvault@latest
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault
npx @bitbonsai/mcpvault@latest ./Vault
npm start
npm start /path/to/your/obsidian/vault
npm start ./Vault
AI Client Configuration
Claude Desktop Add to your Claude Desktop configuration file:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"@bitbonsai/mcpvault@latest",
"/Users/yourname/Documents/MyVault"
]
}
}
}
{
"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"
]
}
}
}
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.
Default search and listing exclusions:
Repeat --exclude <subtree> to hide vault-relative folders from search_notes and list_directory in every session. Per-call excludePaths add to these defaults. Direct read and write tools remain available for excluded paths.
"args": [
"@bitbonsai/mcpvault@latest",
"/Users/yourname/Documents/ResearchVault",
"--exclude", "Archive",
"--exclude", "Snapshots/Old"
]
MCPVault does not read Obsidian's .obsidian/app.json; exclusions stay explicit in the MCP server configuration.
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"]
}
}
}
}
}
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)
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 today's journal entry to my daily note"
"Prepend an urgent task to my todo list"
"Add the tags 'project' and 'urgent' to my task note"
"List all tags in my research note"
"Remove the 'draft' tag from my completed article"
"List all markdown files in my 'Projects' folder"
"Delete the old draft note 'draft-ideas.md' (with confirmation)"
Example workflows
"Summarize my research notes tagged with 'machine-learning' from the last month"
"Update the status in my project notes to 'completed' and add today's date"
"Find notes that mention 'API design' and draft a guide from them"
"Review my untagged notes and suggest tags based on their content"
Troubleshooting
Common Issues
"command not found: npx"
Solution: Install Node.js runtime from nodejs.org
Alternative: Use global install: npm install -g @bitbonsai/mcpvault
"File not found" when paths look correct
Cause: The server is using the wrong vault root
Solution: Either run the command from your vault directory or pass the vault path explicitly
"Permission denied" errors
Cause: Insufficient file system permissions
Solution: Ensure the vault directory is readable/writable by your user
"Path traversal not allowed"
Cause: Trying to access files outside the vault
Solution: All file paths must be relative to the vault root
AI client not recognizing the server
Check the configuration file path is correct for your OS
Ensure JSON syntax is valid (use a JSON validator)
Restart your AI client after configuration changes
Check your AI client's logs for error messages
Verify your AI client supports MCP (Model Context Protocol)
".obsidian files still showing up"
Expected: The path filter automatically excludes .obsidian/** patterns
If still seeing them: The filter is working as designed for security
Debug Mode npx @bitbonsai/mcpvault /path/to/vault 2>debug.log
Getting Help
Open an issue on GitHub
Include your OS, Node.js version, and error messages
Provide the vault directory structure (without sensitive content)
Testing
API Methods
read_noteRead a note from the vault with parsed frontmatter.
{
"name": "read_note",
"arguments": {
"path": "project-ideas.md",
"prettyPrint": false
}
}
{
"fm": {
"title": "Project Ideas",
"tags": ["projects", "brainstorming"],
"created": "2023-01-15T10:30:00.000Z"
},
"content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
Response (with prettyPrint: true):
{
"fm": {
"title": "Project Ideas",
"tags": ["projects", "brainstorming"],
"created": "2023-01-15T10:30:00.000Z"
},
"content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}
write_noteWrite a note to the vault with optional frontmatter and write mode.
overwrite (default): Replace entire file content
append: Add content to the end of existing file
prepend: Add content to the beginning of existing file
{
"name": "write_note",
"arguments": {
"path": "meeting-notes.md",
"content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
"frontmatter": {
"title": "Team Meeting Notes",
"date": "2023-12-01",
"tags": ["meetings", "team"]
},
"mode": "overwrite"
}
}
{
"name": "write_note",
"arguments": {
"path": "daily-log.md",
"content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
"mode": "append"
}
}
{
"message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
patch_noteReplace an exact string inside an existing note without rewriting the full file.
{
"name": "patch_note",
"arguments": {
"path": "meeting-notes.md",
"oldString": "- Next milestones",
"newString": "- Next milestones (owner: Alex)",
"replaceAll": false
}
}
{
"success": true,
"path": "meeting-notes.md",
"message": "Successfully replaced 1 occurrence",
"matchCount": 1
}
Response (multiple matches with replaceAll=false):
{
"success": false,
"path": "meeting-notes.md",
"message": "Found 3 occurrences of the string. Use replaceAll=true to replace all occurrences, or provide a more specific string to match exactly one occurrence.",
"matchCount": 3
}
list_directoryList files and directories in the vault.
Note: this includes non-note filenames (for example pdf, png, jpg) so AI assistants can see vault structure, but note tools like read_note and write_note still operate on note files only (.md, .markdown, .txt, .base, .canvas).
{
"name": "list_directory",
"arguments": {
"path": "Projects",
"prettyPrint": false
}
}
{
"dirs": ["AI-Tools", "Web-Development"],
"files": ["project-template.md", "roadmap.md"]
}
delete_noteDelete a note from the vault (requires confirmation for safety).
{
"name": "delete_note",
"arguments": {
"path": "old-draft.md",
"confirmPath": "old-draft.md",
"trashMode": "local"
}
}
{
"success": true,
"path": "old-draft.md",
"message": "Successfully moved note to vault trash: old-draft.md"
}
none (default): permanent delete
local: move to .trash inside the vault, preserving folder structure
system: move to the OS trash/recycle bin
Response (Confirmation Failed):
{
"success": false,
"path": "old-draft.md",
"message": "Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical."
}
Confirmation: confirmPath must exactly match path before deletion proceeds.
get_frontmatterExtract only the frontmatter from a note without reading the full content.
{
"name": "get_frontmatter",
"arguments": {
"path": "project-ideas.md",
"prettyPrint": false
}
}
Compact response, returning frontmatter directly:
{
"title": "Project Ideas",
"tags": ["projects", "brainstorming"],
"created": "2023-01-15T10:30:00.000Z"
}
manage_tagsAdd, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "list"
}
}
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "add",
"tags": ["machine-learning", "ai", "important"]
}
}
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "remove",
"tags": ["draft", "temporary"]
}
}
{
"path": "research-notes.md",
"operation": "add",
"tags": ["research", "ai", "machine-learning", "important"],
"success": true,
"message": "Successfully added tags"
}
search_notesSearch for notes in the vault by content or frontmatter with multi-word matching and BM25 relevance reranking.
{
"name": "search_notes",
"arguments": {
"query": "machine learning",
"limit": 5,
"searchContent": true,
"searchFrontmatter": false,
"caseSensitive": false,
"prettyPrint": false
}
}
[
{
"p": "ai-research.md",
"t": "AI Research Notes",
"ex": "...machine learning...",
"mc": 2,
"ln": 15,
"uri": "obsidian://open?vault=MyVault&file=ai-research.md"
}
]
p = path
t = title
ex = excerpt (21 chars context)
mc = match count
ln = line number
uri = Obsidian deep link for quick opening
move_noteMove or rename a note in the vault (.md, .markdown, .txt, .base, .canvas).
{
"name": "move_note",
"arguments": {
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"overwrite": false
}
}
{
"success": true,
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"message": "Successfully moved note from drafts/article.md to published/article.md"
}
move_fileMove or rename any file in the vault with binary-safe file operations (file-only; not recursive directory moves). For safety, this tool requires confirmation of both source and destination paths.
{
"name": "move_file",
"arguments": {
"oldPath": "Miro/attachments/Pasted image 20250812140124.png",
"newPath": "assets/images/Pasted image 20250812140124.png",
"confirmOldPath": "Miro/attachments/Pasted image 20250812140124.png",
"confirmNewPath": "assets/images/Pasted image 20250812140124.png",
"overwrite": false
}
}
{
"success": true,
"oldPath": "Miro/attachments/Pasted image 20250812140124.png",
"newPath": "assets/images/Pasted image 20250812140124.png",
"message": "Successfully moved file from Miro/attachments/Pasted image 20250812140124.png to assets/images/Pasted image 20250812140124.png"
}
Confirmation: confirmOldPath must match oldPath, and confirmNewPath must match newPath.
read_multiple_notesRead multiple notes in a batch (maximum 10 files).
{
"name": "read_multiple_notes",
"arguments": {
"paths": ["note1.md", "note2.md", "note3.md"],
"includeContent": true,
"includeFrontmatter": true,
"prettyPrint": false
}
}
{
"ok": [
{
"path": "note1.md",
"frontmatter": { "title": "Note 1" },
"content": "# Note 1\n\nContent here..."
}
],
"err": [{ "path": "note2.md", "error": "File not found" }]
}
ok = successful reads
err = failed reads
update_frontmatterUpdate frontmatter of a note without changing content.
{
"name": "update_frontmatter",
"arguments": {
"path": "research-note.md",
"frontmatter": {
"status": "completed",
"updated": "2025-09-23"
},
"merge": true
}
}
{
"message": "Successfully updated frontmatter for: research-note.md"
}
get_notes_infoGet metadata for notes without reading full content.
{
"name": "get_notes_info",
"arguments": {
"paths": ["note1.md", "note2.md"],
"prettyPrint": false
}
}
Compact response, returning an array directly:
[
{
"path": "note1.md",
"size": 1024,
"modified": 1695456000000,
"hasFrontmatter": true
}
]
get_vault_statsGet high-level vault statistics without reading note contents.
{
"name": "get_vault_stats",
"arguments": {
"recentCount": 5,
"prettyPrint": false
}
}
{
"notes": 1248,
"folders": 76,
"size": 18349210,
"recent": [
{
"path": "Daily/2026-02-27.md",
"modified": 1772188800000,
"size": 2814
}
]
}
Security boundaries MCPVault applies these checks before file operations:
Path Security
Path Traversal Protection: All file paths are validated to prevent access outside the vault
Relative Path Enforcement: Paths are normalized and restricted to the vault directory
Symbolic Link Safety: Resolved paths are checked against vault boundaries
File Filtering
Automatic Exclusions: .obsidian, .git, node_modules, and system files are filtered
Extension Whitelist: Only .md, .markdown, .txt, .base, and .canvas files are accessible by default
Hidden File Protection: Dot files and system directories are automatically excluded
Content Validation
YAML Frontmatter Validation: Frontmatter is parsed and validated before writing
Function/Symbol Prevention: Dangerous JavaScript objects are blocked from frontmatter
Data Type Checking: Only safe data types (strings, numbers, arrays, objects) allowed
Best Practices
Least Privilege: Server only accesses the specified vault directory
Read-Only Mode: Run with --read-only for sensitive vaults; mutating tools are hidden and rejected
Backup Recommended: Always backup your vault before using write operations
Network Isolation: Server uses stdio transport (no network exposure)
What's NOT Protected
File Content: The server can read/write any allowed file content
Vault Structure: Directory structure is visible to AI assistants
File Metadata: Creation times, file sizes, etc. are accessible
Only grant write access to clients and conversations you trust. Use --read-only when the client does not need to modify notes.
Architecture
server.ts - MCP server entry point
src/cli.ts - CLI option parsing for vault path, read-only mode, and default exclusions
src/createServer.ts - MCP tool registration, request routing, and discovery defaults
src/frontmatter.ts - YAML frontmatter handling with gray-matter
src/filesystem.ts - File operations with path validation
src/pathfilter.ts - Directory and file filtering
src/search.ts - Note search functionality with content and frontmatter support
src/uri.ts - Obsidian URI generation for deep links
src/types.ts - TypeScript type definitions
Contributing
Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Ensure all tests pass: npm test
Submit a pull request
Maintainers: production publishing is driven by GitHub Releases. See RELEASING.md .
License
Verzeichnis-Score 10/100 Gelistet 10 von 10
In der offiziellen MCP Registry 0 von 18
Vom Maintainer beansprucht 0 von 8
Antwortet mit einer Tool-Liste 0 von 12
GitHub-Sterne 0 von 16
Wöchentliche Downloads 0 von 10
Ohmyzsh 🙃 A delightful community-driven (with 2,500+ contributors) framework for managing your zsh configuration. Includes 300+ optional plugins (rails, git, macOS, hub, docker, homebrew, node, php, python Ruflo 🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, feder TrendRadar ⭐AI-driven public opinion & trend monitor with multi-platform aggregation, RSS, and smart alerts.🎯 告别信息过载,你的 AI 舆情监控助手与热点筛选工具!聚合多平台热点 + RSS 订阅,支持关键词精准筛选。AI 智能筛选新闻 + AI 翻译 + AI 分析简报直推手机,也支持接入 MCP 架构 Dbx 25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Dock Docker Android Android in docker solution with noVNC supported, video recording, mcp server and AI-agent TREK The most complete open-source travel planner: real-time collaboration, bookings, budgets, packing lists, journals, offline PWA, SSO and an AI-ready MCP server, with planet-wide place search and routin Pansou PanSou是一款高性能的网盘资源搜索API服务,支持TG频道和插件搜索。系统设计以性能和可扩展性为核心,支持多频道多插件并发搜索、结果智能排序和网盘类型分类。docker集成前后端,一键启动,开箱即用。仅供学习研究,请勿以各种形式用于盈利目的。 https://t.me/s/webhtv XHS Downloader 小红书(XiaoHongShu、RedNote)链接提取/作品采集工具 Nginx Ui Yet another WebUI for Nginx Tyk Open Source API and AI Gateway supporting REST, GraphQL, TCP, gRPC and MCP (Model Context Protocol) Openstatus Open-source status page, incident response and uptime monitoring Dashboard Icons 3,400+ curated icons and logos for dashboards and AI agents. SVG, PNG and WEBP on a free CDN, plus an MCP server for Claude Code, Codex, ChatGPT, Cursor, Hermes and OpenClaw. MCP-Server für DevOps Die besten MCP-Server für DevOps azure-compute Azure VM/VMSS router. WHEN: create / provision / deploy / spin-up VM, recommend VM size, compare VM pricing, VMSS, scale set, autoscale, burstable, lightweight server, website, backend, GPU, machine l self-hosted-funnel-launch Deploy a self-hosted funnel builder, take a funnel from empty install to published - landing page, checkout, one-click upsell, thank-you - and drive it from an agent over MCP. Covers deploying to Clou
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
Wie installiere ich @bitbonsai/mcpvault? Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Benötigt @bitbonsai/mcpvault einen API-Schlüssel? In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
Welchen Transport verwendet @bitbonsai/mcpvault? @bitbonsai/mcpvault läuft lokal über stdio.
Wann wurde @bitbonsai/mcpvault zuletzt geprüft? Zuletzt geprüft: 2026-11-16. Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant
Tools haben Beschreibungen 0 von 6