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
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.)
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
Run with error logging:
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
Run the test suite:
npm test
API Methods
read_note
Read a note from the vault with parsed frontmatter.
Request:
{
"name": "read_note",
"arguments": {
"path": "project-ideas.md",
"prettyPrint": false
}
}
Compact response:
{
"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_note
Write a note to the vault with optional frontmatter and write mode.
Write Modes:
overwrite (default): Replace entire file contentappend: Add content to the end of existing fileprepend: Add content to the beginning of existing file
Request (Overwrite):
{
"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"
}
}
Request (Append):
{
"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"
}
}
Response:
{
"message": "Successfully wrote note: meeting-notes.md (mode: overwrite)"
}
patch_note
Replace an exact string inside an existing note without rewriting the full file.
Request:
{
"name": "patch_note",
"arguments": {
"path": "meeting-notes.md",
"oldString": "- Next milestones",
"newString": "- Next milestones (owner: Alex)",
"replaceAll": false
}
}
Response (success):
{
"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_directory
List 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).
Request:
{
"name": "list_directory",
"arguments": {
"path": "Projects",
"prettyPrint": false
}
}
Compact response:
{
"dirs": ["AI-Tools", "Web-Development"],
"files": ["project-template.md", "roadmap.md"]
}
delete_note
Delete a note from the vault (requires confirmation for safety).
Request:
{
"name": "delete_note",
"arguments": {
"path": "old-draft.md",
"confirmPath": "old-draft.md",
"trashMode": "local"
}
}
Response (Success):
{
"success": true,
"path": "old-draft.md",
"message": "Successfully moved note to vault trash: old-draft.md"
}
Trash modes:
none (default): permanent deletelocal: move to .trash inside the vault, preserving folder structuresystem: 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_frontmatter
Extract only the frontmatter from a note without reading the full content.
Request:
{
"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_tags
Add, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.
Request (List Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "list"
}
}
Request (Add Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "add",
"tags": ["machine-learning", "ai", "important"]
}
}
Request (Remove Tags):
{
"name": "manage_tags",
"arguments": {
"path": "research-notes.md",
"operation": "remove",
"tags": ["draft", "temporary"]
}
}
Response:
{
"path": "research-notes.md",
"operation": "add",
"tags": ["research", "ai", "machine-learning", "important"],
"success": true,
"message": "Successfully added tags"
}
search_notes
Search for notes in the vault by content or frontmatter with multi-word matching and BM25 relevance reranking.
Request:
{
"name": "search_notes",
"arguments": {
"query": "machine learning",
"limit": 5,
"searchContent": true,
"searchFrontmatter": false,
"caseSensitive": false,
"prettyPrint": false
}
}
Compact response:
[
{
"p": "ai-research.md",
"t": "AI Research Notes",
"ex": "...machine learning...",
"mc": 2,
"ln": 15,
"uri": "obsidian://open?vault=MyVault&file=ai-research.md"
}
]
Field names:
p = patht = titleex = excerpt (21 chars context)mc = match countln = line numberuri = Obsidian deep link for quick opening
move_note
Move or rename a note in the vault (.md, .markdown, .txt, .base, .canvas).
Request:
{
"name": "move_note",
"arguments": {
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"overwrite": false
}
}
Response:
{
"success": true,
"oldPath": "drafts/article.md",
"newPath": "published/article.md",
"message": "Successfully moved note from drafts/article.md to published/article.md"
}
move_file
Move 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.
Request:
{
"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
}
}
Response:
{
"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_notes
Read multiple notes in a batch (maximum 10 files).
Request:
{
"name": "read_multiple_notes",
"arguments": {
"paths": ["note1.md", "note2.md", "note3.md"],
"includeContent": true,
"includeFrontmatter": true,
"prettyPrint": false
}
}
Compact response:
{
"ok": [
{
"path": "note1.md",
"frontmatter": { "title": "Note 1" },
"content": "# Note 1\n\nContent here..."
}
],
"err": [{ "path": "note2.md", "error": "File not found" }]
}
Field names:
ok = successful readserr = failed reads
update_frontmatter
Update frontmatter of a note without changing content.
Request:
{
"name": "update_frontmatter",
"arguments": {
"path": "research-note.md",
"frontmatter": {
"status": "completed",
"updated": "2025-09-23"
},
"merge": true
}
}
Response:
{
"message": "Successfully updated frontmatter for: research-note.md"
}
get_notes_info
Get metadata for notes without reading full content.
Request:
{
"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_stats
Get high-level vault statistics without reading note contents.
Request:
{
"name": "get_vault_stats",
"arguments": {
"recentCount": 5,
"prettyPrint": false
}
}
Compact response:
{
"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 pointsrc/cli.ts - CLI option parsing for vault path, read-only mode, and default exclusionssrc/createServer.ts - MCP tool registration, request routing, and discovery defaultssrc/frontmatter.ts - YAML frontmatter handling with gray-mattersrc/filesystem.ts - File operations with path validationsrc/pathfilter.ts - Directory and file filteringsrc/search.ts - Note search functionality with content and frontmatter supportsrc/uri.ts - Obsidian URI generation for deep linkssrc/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
MIT