{
"markdown": "\n\n# MCPVault\n\n[](https://mcptoplist.com/server/glama%2Fbitbonsai%2Fmcpvault)\n\nA 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.\n\n\n \n[https://mcpvault.org](https://mcpvault.org)\n\n[Changelog](./CHANGELOG.md)\n\n
\n\n\n\n[](https://github.com/bitbonsai/mcpvault) [](https://www.npmjs.com/package/@bitbonsai/mcpvault) [](https://www.npmjs.com/package/@bitbonsai/mcpvault) [](https://github.com/sponsors/bitbonsai) [](https://ko-fi.com/bitbonsai) [](https://liberapay.com/bitbonsai/)\n\n
\n\n## Supported clients\n\nConfiguration 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.\n\nhttps://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c\n\n## Quick start\n\n1. **Install Node.js runtime:**\n\n ```bash\n # Download from https://nodejs.org (v20.0.0 or later)\n # or use a package manager like nvm, brew, apt, etc.\n ```\n\n2. **Test the server:**\n\n If using the published package:\n\n ```bash\n npx @modelcontextprotocol/inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault\n ```\n\n3. **Configure your AI client:**\n\n **Claude Desktop** - Copy this to `claude_desktop_config.json`:\n\n ```json\n {\n \"mcpServers\": {\n \"obsidian\": {\n \"command\": \"npx\",\n \"args\": [\"@bitbonsai/mcpvault@latest\", \"/path/to/your/vault\"]\n }\n }\n }\n ```\n\n **Claude Code** - Copy this to `~/.claude.json`:\n\n ```json\n {\n \"mcpServers\": {\n \"obsidian\": {\n \"command\": \"npx\",\n \"args\": [\"@bitbonsai/mcpvault@latest\", \"/path/to/your/vault\"],\n \"env\": {}\n }\n }\n }\n ```\n\n **OpenCode** - Copy this to `~/.config/opencode/opencode.json`\n\n ```json\n {\n \"mcp\": {\n \"obsidian\": {\n \"type\": \"local\",\n \"command\": [\n \"npx\",\n \"@bitbonsai/mcpvault@latest\",\n \"/path/to/your/vault/\"\n ],\n \"enabled\": true\n }\n }\n }\n ```\n\n Replace `/path/to/your/vault` with your actual Obsidian vault path.\n\n For other platforms, see [detailed configuration guides](#ai-client-configuration) below.\n\n4. **Test with your AI:**\n - \"List files in my Obsidian vault\"\n - \"Read my note called 'project-ideas.md'\"\n - \"Create a new note with today's date\"\n\nTo verify the connection, ask your client to list MCPVault tools or read a known note.\n\n## How it connects\n\nAn 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.\n\n## Features\n\n- AST-aware frontmatter updates preserve formatting for unchanged YAML fields.\n- Path checks block traversal, symlink escapes, dotfiles, `.obsidian`, `.git`, and `node_modules`.\n- Eighteen MCP tools cover note and file operations:\n - File operations: `read_note`, `write_note`, `patch_note`, `delete_note`, `move_note`, `move_file`\n - Partial reads: `get_note_outline`, `read_note_lines`\n - Directory and batch reads: `list_directory`, `read_multiple_notes`\n - Search: `search_notes` with multi-word matching and BM25 reranking\n - Metadata and tags: `get_frontmatter`, `update_frontmatter`, `get_notes_info`, `get_vault_stats`, `manage_tags`, `list_all_tags`\n - Wiki links: `wiki_link` resolves names and returns alternative paths when a name is ambiguous\n- `write_note` supports overwrite, append, and prepend modes.\n- `delete_note` and `move_file` require matching confirmation paths.\n- Path arguments are trimmed before validation.\n- Search and batch tools return compact fields by default; set `prettyPrint: true` for expanded output.\n- The package exports TypeScript declarations and public types.\n- MCPVault requires no Obsidian plugin.\n\n## Prerequisites\n\n- [Node.js](https://nodejs.org) runtime (v20.0.0 or later)\n- An Obsidian vault (local directory with `.md`, `.markdown`, `.txt`, `.base`, or `.canvas` files)\n- MCP-compatible AI client (Claude Desktop, ChatGPT Desktop, Claude Code, etc.)\n\n## Installation\n\n### For end users\n\n`npx` downloads and runs the package:\n\n```bash\nnpx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault\n```\n\nIf you omit the vault path, the server uses your current working directory as the vault root.\n\n### For developers\n\n1. Clone this repository\n2. Use the correct Node.js version:\n\n```bash\nnvm use # Uses Node 24 from .nvmrc\n```\n\n3. Install dependencies with npm:\n\n```bash\nnpm install # Corepack automatically uses npm 10.9.0\n```\n\n4. Test locally with MCP inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector npm start /path/to/your/vault\n```\n\nUse MCP Inspector to test the server before adding it to a client:\n\n```bash\n# Install globally for easier access\nnpm install -g @modelcontextprotocol/inspector\n\n# Test with any vault\nmcp-inspector npx @bitbonsai/mcpvault@latest /path/to/your/vault\n```\n\n## Usage\n\n### Running the Server\n\n**End users:**\n\n```bash\nnpx @bitbonsai/mcpvault@latest\nnpx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault\nnpx @bitbonsai/mcpvault@latest ./Vault\n```\n\n**Developers:**\n\n```bash\nnpm start\nnpm start /path/to/your/obsidian/vault\nnpm start ./Vault\n```\n\n### AI Client Configuration\n\n#### Claude Desktop\n\nAdd to your Claude Desktop configuration file:\n\n**Single Vault:**\n\n```json\n{\n \"mcpServers\": {\n \"obsidian\": {\n \"command\": \"npx\",\n \"args\": [\n \"@bitbonsai/mcpvault@latest\",\n \"/Users/yourname/Documents/MyVault\"\n ]\n }\n }\n}\n```\n\n**Multiple Vaults:**\n\n```json\n{\n \"mcpServers\": {\n \"obsidian-personal\": {\n \"command\": \"npx\",\n \"args\": [\n \"@bitbonsai/mcpvault@latest\",\n \"/Users/yourname/Documents/PersonalVault\"\n ]\n },\n \"obsidian-work\": {\n \"command\": \"npx\",\n \"args\": [\n \"@bitbonsai/mcpvault@latest\",\n \"/Users/yourname/Documents/WorkVault\"\n ]\n }\n }\n}\n```\n\n**Read-only mode:**\n\nAdd `--read-only` after the vault path to expose only read tools. Mutating tools are omitted from discovery and rejected if called directly.\n\n```json\n{\n \"mcpServers\": {\n \"obsidian-read-only\": {\n \"command\": \"npx\",\n \"args\": [\n \"@bitbonsai/mcpvault@latest\",\n \"/Users/yourname/Documents/ResearchVault\",\n \"--read-only\"\n ]\n }\n }\n}\n```\n\nThe 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.\n\n**Configuration File Locations:**\n\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `C:\\Users\\{username}\\AppData\\Roaming\\Claude\\claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n_You can also access this through Claude Desktop → Settings → Developer → Edit Config_\n\n#### ChatGPT Desktop\n\n**Requirements:** ChatGPT Enterprise, Education, or Team subscription (not available for individual Plus users)\n\nChatGPT uses MCP through Deep Research and developer mode. Configuration is done through the ChatGPT interface:\n\n1. Access ChatGPT developer mode (beta feature)\n2. Configure MCP servers through the built-in MCP client\n3. Create custom connectors for your organization\n\n_Note: ChatGPT Desktop's MCP integration is currently limited to enterprise subscriptions and uses a different setup process than file-based configuration._\n\n#### Claude Code\n\nClaude Code uses `.claude.json` configuration file:\n\n**User-scoped (recommended):** Edit `~/.claude.json`:\n\n```json\n{\n \"mcpServers\": {\n \"obsidian\": {\n \"command\": \"npx\",\n \"args\": [\"@bitbonsai/mcpvault@latest\", \"/path/to/your/vault\"],\n \"env\": {}\n }\n }\n}\n```\n\n**Project-scoped:** Edit `.claude.json` in your project or add to the projects section:\n\n```json\n{\n \"projects\": {\n \"/path/to/your/project\": {\n \"mcpServers\": {\n \"obsidian\": {\n \"command\": \"npx\",\n \"args\": [\"@bitbonsai/mcpvault@latest\", \"/path/to/your/vault\"]\n }\n }\n }\n }\n}\n```\n\n**Using Claude Code CLI:**\n\n```bash\nclaude mcp add obsidian --scope user npx @bitbonsai/mcpvault /path/to/your/vault\n```\n\n#### Goose Desktop\n\nOn Goose Desktop settings, click **Add custom extension**, and on the command field add:\n\n```bash\nnpx @bitbonsai/mcpvault@latest /path/to/your/vault\n```\n\n#### Other MCP-Compatible Clients (2025)\n\n**Confirmed MCP Support:**\n\n- **IntelliJ IDEA 2025.1+** - Native MCP client support\n- **Cursor IDE** - Built-in MCP compatibility\n- **Windsurf IDE** - Full MCP integration\n- **[Ontheia](https://ontheia.ai)** - Self-hosted, open-source AI agent platform\n- **Zed, Replit, Codeium, Sourcegraph** - In development\n- **Microsoft Copilot Studio** - Native MCP support with one-click server connections\n\nMost modern MCP clients use similar JSON configuration patterns. Refer to your specific client's documentation for exact setup instructions.\n\n### Examples\n\n#### Ask your AI assistant about your notes:\n\n- \"What files are in my Obsidian vault?\"\n- \"Read my note called 'project-ideas.md'\"\n- \"Show me all notes with 'AI' in the title\"\n\n#### Have your AI assistant help with note management:\n\n- \"Create a new note called 'meeting-notes.md' with today's date in the frontmatter\"\n- \"Append today's journal entry to my daily note\"\n- \"Prepend an urgent task to my todo list\"\n- \"Add the tags 'project' and 'urgent' to my task note\"\n- \"List all tags in my research note\"\n- \"Remove the 'draft' tag from my completed article\"\n- \"List all markdown files in my 'Projects' folder\"\n- \"Delete the old draft note 'draft-ideas.md' (with confirmation)\"\n\n#### Example workflows\n\n- \"Summarize my research notes tagged with 'machine-learning' from the last month\"\n- \"Update the status in my project notes to 'completed' and add today's date\"\n- \"Find notes that mention 'API design' and draft a guide from them\"\n- \"Review my untagged notes and suggest tags based on their content\"\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"command not found: npx\"\n\n- **Solution:** Install Node.js runtime from [nodejs.org](https://nodejs.org)\n- **Alternative:** Use global install: `npm install -g @bitbonsai/mcpvault`\n\n#### \"File not found\" when paths look correct\n\n- **Cause:** The server is using the wrong vault root\n- **Solution:** Either run the command from your vault directory or pass the vault path explicitly\n\n#### \"Permission denied\" errors\n\n- **Cause:** Insufficient file system permissions\n- **Solution:** Ensure the vault directory is readable/writable by your user\n\n#### \"Path traversal not allowed\"\n\n- **Cause:** Trying to access files outside the vault\n- **Solution:** All file paths must be relative to the vault root\n\n#### AI client not recognizing the server\n\n1. Check the configuration file path is correct for your OS\n2. Ensure JSON syntax is valid (use a JSON validator)\n3. Restart your AI client after configuration changes\n4. Check your AI client's logs for error messages\n5. Verify your AI client supports MCP (Model Context Protocol)\n\n#### \".obsidian files still showing up\"\n\n- **Expected:** The path filter automatically excludes `.obsidian/**` patterns\n- **If still seeing them:** The filter is working as designed for security\n\n### Debug Mode\n\nRun with error logging:\n\n```bash\nnpx @bitbonsai/mcpvault /path/to/vault 2>debug.log\n```\n\n### Getting Help\n\n- [Open an issue](https://github.com/bitbonsai/mcpvault/issues) on GitHub\n- Include your OS, Node.js version, and error messages\n- Provide the vault directory structure (without sensitive content)\n\n## Testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\n## API Methods\n\n### `read_note`\n\nRead a note from the vault with parsed frontmatter.\n\n**Request:**\n\n```json\n{\n \"name\": \"read_note\",\n \"arguments\": {\n \"path\": \"project-ideas.md\",\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response:**\n\n```json\n{\n \"fm\": {\n \"title\": \"Project Ideas\",\n \"tags\": [\"projects\", \"brainstorming\"],\n \"created\": \"2023-01-15T10:30:00.000Z\"\n },\n \"content\": \"# Project Ideas\\n\\n## AI Tools\\n- MCP server for Obsidian\\n- Voice note transcription\\n\\n## Web Apps\\n- Task management system\"\n}\n```\n\n**Response (with prettyPrint: true):**\n\n```json\n{\n \"fm\": {\n \"title\": \"Project Ideas\",\n \"tags\": [\"projects\", \"brainstorming\"],\n \"created\": \"2023-01-15T10:30:00.000Z\"\n },\n \"content\": \"# Project Ideas\\n\\n## AI Tools\\n- MCP server for Obsidian\\n- Voice note transcription\\n\\n## Web Apps\\n- Task management system\"\n}\n```\n\n### `write_note`\n\nWrite a note to the vault with optional frontmatter and write mode.\n\n**Write Modes:**\n\n- `overwrite` (default): Replace entire file content\n- `append`: Add content to the end of existing file\n- `prepend`: Add content to the beginning of existing file\n\n**Request (Overwrite):**\n\n```json\n{\n \"name\": \"write_note\",\n \"arguments\": {\n \"path\": \"meeting-notes.md\",\n \"content\": \"# Team Meeting\\n\\n## Agenda\\n- Project updates\\n- Next milestones\",\n \"frontmatter\": {\n \"title\": \"Team Meeting Notes\",\n \"date\": \"2023-12-01\",\n \"tags\": [\"meetings\", \"team\"]\n },\n \"mode\": \"overwrite\"\n }\n}\n```\n\n**Request (Append):**\n\n```json\n{\n \"name\": \"write_note\",\n \"arguments\": {\n \"path\": \"daily-log.md\",\n \"content\": \"\\n\\n## 3:00 PM Update\\n- Completed project review\\n- Started new feature\",\n \"mode\": \"append\"\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"message\": \"Successfully wrote note: meeting-notes.md (mode: overwrite)\"\n}\n```\n\n### `patch_note`\n\nReplace an exact string inside an existing note without rewriting the full file.\n\n**Request:**\n\n```json\n{\n \"name\": \"patch_note\",\n \"arguments\": {\n \"path\": \"meeting-notes.md\",\n \"oldString\": \"- Next milestones\",\n \"newString\": \"- Next milestones (owner: Alex)\",\n \"replaceAll\": false\n }\n}\n```\n\n**Response (success):**\n\n```json\n{\n \"success\": true,\n \"path\": \"meeting-notes.md\",\n \"message\": \"Successfully replaced 1 occurrence\",\n \"matchCount\": 1\n}\n```\n\n**Response (multiple matches with replaceAll=false):**\n\n```json\n{\n \"success\": false,\n \"path\": \"meeting-notes.md\",\n \"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.\",\n \"matchCount\": 3\n}\n```\n\n### `list_directory`\n\nList files and directories in the vault.\n\nNote: 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`).\n\n**Request:**\n\n```json\n{\n \"name\": \"list_directory\",\n \"arguments\": {\n \"path\": \"Projects\",\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response:**\n\n```json\n{\n \"dirs\": [\"AI-Tools\", \"Web-Development\"],\n \"files\": [\"project-template.md\", \"roadmap.md\"]\n}\n```\n\n### `delete_note`\n\nDelete a note from the vault (requires confirmation for safety).\n\n**Request:**\n\n```json\n{\n \"name\": \"delete_note\",\n \"arguments\": {\n \"path\": \"old-draft.md\",\n \"confirmPath\": \"old-draft.md\",\n \"trashMode\": \"local\"\n }\n}\n```\n\n**Response (Success):**\n\n```json\n{\n \"success\": true,\n \"path\": \"old-draft.md\",\n \"message\": \"Successfully moved note to vault trash: old-draft.md\"\n}\n```\n\n**Trash modes:**\n- `none` (default): permanent delete\n- `local`: move to `.trash` inside the vault, preserving folder structure\n- `system`: move to the OS trash/recycle bin\n\n**Response (Confirmation Failed):**\n\n```json\n{\n \"success\": false,\n \"path\": \"old-draft.md\",\n \"message\": \"Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical.\"\n}\n```\n\n**Confirmation:** `confirmPath` must exactly match `path` before deletion proceeds.\n\n### `get_frontmatter`\n\nExtract only the frontmatter from a note without reading the full content.\n\n**Request:**\n\n```json\n{\n \"name\": \"get_frontmatter\",\n \"arguments\": {\n \"path\": \"project-ideas.md\",\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response, returning frontmatter directly:**\n\n```json\n{\n \"title\": \"Project Ideas\",\n \"tags\": [\"projects\", \"brainstorming\"],\n \"created\": \"2023-01-15T10:30:00.000Z\"\n}\n```\n\n### `manage_tags`\n\nAdd, remove, or list tags in a note. Tags are managed in the frontmatter and inline tags are detected.\n\n**Request (List Tags):**\n\n```json\n{\n \"name\": \"manage_tags\",\n \"arguments\": {\n \"path\": \"research-notes.md\",\n \"operation\": \"list\"\n }\n}\n```\n\n**Request (Add Tags):**\n\n```json\n{\n \"name\": \"manage_tags\",\n \"arguments\": {\n \"path\": \"research-notes.md\",\n \"operation\": \"add\",\n \"tags\": [\"machine-learning\", \"ai\", \"important\"]\n }\n}\n```\n\n**Request (Remove Tags):**\n\n```json\n{\n \"name\": \"manage_tags\",\n \"arguments\": {\n \"path\": \"research-notes.md\",\n \"operation\": \"remove\",\n \"tags\": [\"draft\", \"temporary\"]\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"path\": \"research-notes.md\",\n \"operation\": \"add\",\n \"tags\": [\"research\", \"ai\", \"machine-learning\", \"important\"],\n \"success\": true,\n \"message\": \"Successfully added tags\"\n}\n```\n\n### `search_notes`\n\nSearch for notes in the vault by content or frontmatter with multi-word matching and BM25 relevance reranking.\n\n**Request:**\n\n```json\n{\n \"name\": \"search_notes\",\n \"arguments\": {\n \"query\": \"machine learning\",\n \"limit\": 5,\n \"searchContent\": true,\n \"searchFrontmatter\": false,\n \"caseSensitive\": false,\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response:**\n\n```json\n[\n {\n \"p\": \"ai-research.md\",\n \"t\": \"AI Research Notes\",\n \"ex\": \"...machine learning...\",\n \"mc\": 2,\n \"ln\": 15,\n \"uri\": \"obsidian://open?vault=MyVault&file=ai-research.md\"\n }\n]\n```\n\n**Field names:**\n\n- `p` = path\n- `t` = title\n- `ex` = excerpt (21 chars context)\n- `mc` = match count\n- `ln` = line number\n- `uri` = Obsidian deep link for quick opening\n\n### `move_note`\n\nMove or rename a note in the vault (`.md`, `.markdown`, `.txt`, `.base`, `.canvas`).\n\n**Request:**\n\n```json\n{\n \"name\": \"move_note\",\n \"arguments\": {\n \"oldPath\": \"drafts/article.md\",\n \"newPath\": \"published/article.md\",\n \"overwrite\": false\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"success\": true,\n \"oldPath\": \"drafts/article.md\",\n \"newPath\": \"published/article.md\",\n \"message\": \"Successfully moved note from drafts/article.md to published/article.md\"\n}\n```\n\n### `move_file`\n\nMove 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.\n\n**Request:**\n\n```json\n{\n \"name\": \"move_file\",\n \"arguments\": {\n \"oldPath\": \"Miro/attachments/Pasted image 20250812140124.png\",\n \"newPath\": \"assets/images/Pasted image 20250812140124.png\",\n \"confirmOldPath\": \"Miro/attachments/Pasted image 20250812140124.png\",\n \"confirmNewPath\": \"assets/images/Pasted image 20250812140124.png\",\n \"overwrite\": false\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"success\": true,\n \"oldPath\": \"Miro/attachments/Pasted image 20250812140124.png\",\n \"newPath\": \"assets/images/Pasted image 20250812140124.png\",\n \"message\": \"Successfully moved file from Miro/attachments/Pasted image 20250812140124.png to assets/images/Pasted image 20250812140124.png\"\n}\n```\n\n**Confirmation:** `confirmOldPath` must match `oldPath`, and `confirmNewPath` must match `newPath`.\n\n### `read_multiple_notes`\n\nRead multiple notes in a batch (maximum 10 files).\n\n**Request:**\n\n```json\n{\n \"name\": \"read_multiple_notes\",\n \"arguments\": {\n \"paths\": [\"note1.md\", \"note2.md\", \"note3.md\"],\n \"includeContent\": true,\n \"includeFrontmatter\": true,\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response:**\n\n```json\n{\n \"ok\": [\n {\n \"path\": \"note1.md\",\n \"frontmatter\": { \"title\": \"Note 1\" },\n \"content\": \"# Note 1\\n\\nContent here...\"\n }\n ],\n \"err\": [{ \"path\": \"note2.md\", \"error\": \"File not found\" }]\n}\n```\n\n**Field names:**\n\n- `ok` = successful reads\n- `err` = failed reads\n\n### `update_frontmatter`\n\nUpdate frontmatter of a note without changing content.\n\n**Request:**\n\n```json\n{\n \"name\": \"update_frontmatter\",\n \"arguments\": {\n \"path\": \"research-note.md\",\n \"frontmatter\": {\n \"status\": \"completed\",\n \"updated\": \"2025-09-23\"\n },\n \"merge\": true\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"message\": \"Successfully updated frontmatter for: research-note.md\"\n}\n```\n\n### `get_notes_info`\n\nGet metadata for notes without reading full content.\n\n**Request:**\n\n```json\n{\n \"name\": \"get_notes_info\",\n \"arguments\": {\n \"paths\": [\"note1.md\", \"note2.md\"],\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response, returning an array directly:**\n\n```json\n[\n {\n \"path\": \"note1.md\",\n \"size\": 1024,\n \"modified\": 1695456000000,\n \"hasFrontmatter\": true\n }\n]\n```\n\n### `get_vault_stats`\n\nGet high-level vault statistics without reading note contents.\n\n**Request:**\n\n```json\n{\n \"name\": \"get_vault_stats\",\n \"arguments\": {\n \"recentCount\": 5,\n \"prettyPrint\": false\n }\n}\n```\n\n**Compact response:**\n\n```json\n{\n \"notes\": 1248,\n \"folders\": 76,\n \"size\": 18349210,\n \"recent\": [\n {\n \"path\": \"Daily/2026-02-27.md\",\n \"modified\": 1772188800000,\n \"size\": 2814\n }\n ]\n}\n```\n\n## Security boundaries\n\nMCPVault applies these checks before file operations:\n\n### Path Security\n\n- **Path Traversal Protection:** All file paths are validated to prevent access outside the vault\n- **Relative Path Enforcement:** Paths are normalized and restricted to the vault directory\n- **Symbolic Link Safety:** Resolved paths are checked against vault boundaries\n\n### File Filtering\n\n- **Automatic Exclusions:** `.obsidian`, `.git`, `node_modules`, and system files are filtered\n- **Extension Whitelist:** Only `.md`, `.markdown`, `.txt`, `.base`, and `.canvas` files are accessible by default\n- **Hidden File Protection:** Dot files and system directories are automatically excluded\n\n### Content Validation\n\n- **YAML Frontmatter Validation:** Frontmatter is parsed and validated before writing\n- **Function/Symbol Prevention:** Dangerous JavaScript objects are blocked from frontmatter\n- **Data Type Checking:** Only safe data types (strings, numbers, arrays, objects) allowed\n\n### Best Practices\n\n- **Least Privilege:** Server only accesses the specified vault directory\n- **Read-Only Mode:** Run with `--read-only` for sensitive vaults; mutating tools are hidden and rejected\n- **Backup Recommended:** Always backup your vault before using write operations\n- **Network Isolation:** Server uses stdio transport (no network exposure)\n\n### What's NOT Protected\n\n- **File Content:** The server can read/write any allowed file content\n- **Vault Structure:** Directory structure is visible to AI assistants\n- **File Metadata:** Creation times, file sizes, etc. are accessible\n\nOnly grant write access to clients and conversations you trust. Use `--read-only` when the client does not need to modify notes.\n\n## Architecture\n\n- `server.ts` - MCP server entry point\n- `src/frontmatter.ts` - YAML frontmatter handling with gray-matter\n- `src/filesystem.ts` - File operations with path validation\n- `src/pathfilter.ts` - Directory and file filtering\n- `src/search.ts` - Note search functionality with content and frontmatter support\n- `src/uri.ts` - Obsidian URI generation for deep links\n- `src/types.ts` - TypeScript type definitions\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Ensure all tests pass: `npm test`\n5. Submit a pull request\n\nMaintainers: production publishing is driven by GitHub Releases. See [RELEASING.md](RELEASING.md).\n\n## License\n\nMIT\n",
"bytes": 24904,
"sha": "8bc5af346ddb268baa4767429ab99001872507b5b807a766e6cca50d949bd2a8",
"repo_slug": "bitbonsai/mcpvault",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/skl_bitbonsai_mcpvault_obsidian_61e20676/readme"
}