# @bitbonsai/mcpvault [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/bitbonsai/mcpvault  
**GitHub Stars:** 1713  
**npm Downloads (last month):** 68134  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/bitbonsai-mcpvault

## Description
Universal AI bridge for Obsidian vaults - connect any MCP-compatible assistant

## Tools
Capabilities this server exposes over MCP:

- **read_note** — Read a note from the Obsidian vault
- **write_note** — Write a note to the Obsidian vault
- **patch_note** — Efficiently update part of a note by replacing a specific string. This is more efficient than rewriting the entire note for small changes.
- **list_directory** — List files and directories in the vault (includes non-note filenames, while read/write tools remain note-only)
- **delete_note** — Delete a note from the Obsidian vault (requires confirmation). Supports permanent delete, vault trash, or system trash.
- **search_notes** — Search for notes in the vault by content or frontmatter
- **move_note** — Move or rename a note in the vault
- **move_file** — Move or rename any file in the vault (binary-safe, file-only, requires confirmation)
- **read_multiple_notes** — Read multiple notes in a batch (max 10 files)
- **update_frontmatter** — Update frontmatter of a note without changing content
- **get_notes_info** — Get metadata for notes without reading full content
- **get_frontmatter** — Extract frontmatter from a note without reading the content
- **manage_tags** — Add, remove, or list tags in a note
- **get_vault_stats** — Get vault statistics including total notes, folders, size, and recently modified files. Useful for understanding vault scope before batch operations.
- **list_all_tags** — List all tags across the vault with occurrence counts. Returns both frontmatter tags and inline #hashtags, deduplicated and sorted by frequency. Useful for discovering existing tags before creating or organizing notes.
- **wiki_link** — Read an Obsidian wiki link. Accepts the same syntax as Obsidian: [[Document Name]] or [[Document Name|Display Text]], including table-authored escapes like [[Document Name\|Display]] and path-qualified links like [[folder/Document Name]]. A #fragment suffix in the input is ignored. Searches the vault for an exact basename match (or exact vault-relative path match when the name contains '/') and returns the file's content. When multiple files share the basename, picks the first (vault root first, then alphabetical by path) and lists the other paths in structuredContent.alternatives. Content is returned bare — ready for direct use in context.
- **get_note_outline** — Get the heading structure of a note without reading its full content. Returns headings with level, text, and line number. Use this first to navigate large notes efficiently, then call read_note_lines to read only the section you need.
- **read_note_lines** — Read a specific line range from a note. Use after get_note_outline to read only the section you need instead of the full file.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcpvault": {
    "command": "npx",
    "args": ["@bitbonsai/mcpvault@latest"]
  }
}
```

## Documentation

## What @bitbonsai/mcpvault does

@bitbonsai/mcpvault gives MCP clients access to a local Obsidian vault. It can inspect, search, create, modify, rename, and remove notes, while also handling selected non-note files. The server operates against a configured vault root and keeps file operations within that root.

Obsidian does not need to be open, and no Obsidian plugin is required. Supported vault content includes `.md`, `.markdown`, `.txt`, `.base`, and `.canvas` files. Note-oriented operations remain limited to notes, while directory listing and file movement can include other filenames.

## How it works

An MCP client launches the package as a local stdio process and passes the vault path as a command-line argument. If no path is supplied, the working directory becomes the vault root. Multiple vaults can be exposed by defining separate MCP server entries with different paths.

Path validation blocks traversal and symlink escapes, along with access to dotfiles, `.obsidian`, `.git`, and `node_modules`. Search and directory listing can also use repeated default exclusions, while per-call exclusions add further paths for that request. Direct read and write operations remain available for excluded paths.

The server supports read-only operation through the `--read-only` option. In that mode, mutating tools are omitted from discovery and rejected if called directly. Destructive deletion and binary-safe file moves require matching confirmation paths.

## Setup and configuration

Install Node.js 22.12.0 or later and provide an Obsidian vault directory. End users can run the published package with:

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

Use the MCP Inspector to test the connection before adding it to a client:

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

For a local development checkout, install dependencies with npm and start the server using `npm start`, optionally followed by the vault path. Client configuration uses the `npx` command and passes `@bitbonsai/mcpvault@latest` plus the vault location. The server supports Claude Desktop, Claude Code, ChatGPT Desktop for Enterprise, Education, or Team accounts, OpenCode, Gemini CLI, OpenAI Codex, IntelliJ IDEA 2025.1 or later, Cursor, Windsurf, and Ontheia when configured for local stdio MCP servers.

## Tools and capabilities

- Read, create, append to, prepend, patch, delete, move, and rename notes with `read_note`, `write_note`, `patch_note`, `delete_note`, and `move_note`.
- Move any vault file with `move_file`, including binary files.
- Browse files and folders with `list_directory`, or read up to 10 notes in one batch with `read_multiple_notes`.
- Search note content and frontmatter with multi-word matching and BM25 reranking through `search_notes`.
- Inspect frontmatter, note metadata, vault totals, folders, size, and recent changes with `get_frontmatter`, `get_notes_info`, and `get_vault_stats`.
- Update YAML frontmatter without changing note content, and add, remove, or list tags with `update_frontmatter` and `manage_tags`.
- Discover tag usage across frontmatter and inline hashtags with `list_all_tags`.
- Resolve Obsidian wiki-link syntax with `wiki_link`, including display-text, escaped table, and path-qualified forms. Ambiguous basename matches include alternative paths.
- Navigate large notes using `get_note_outline` followed by `read_note_lines`, avoiding a full-note read when only a section is needed.

## Limitations and notes

The server is local and file-based: the client process must be able to access the vault directory. Read and write tools operate on notes, while `list_directory` and `move_file` cover broader file types. Batch note reads are limited to 10 files. Search and batch responses use compact fields by default; callers can request expanded output with `prettyPrint: true`. Unchanged YAML frontmatter fields retain their formatting during AST-aware updates.

_Full upstream README: https://allmcps.com/mcp/bitbonsai-mcpvault/readme_