# bitbonsai/mcp-obsidian [Health: Active]

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

## Description
Universal AI bridge for Obsidian vaults using MCP. Provides safe read/write access to notes with 11 comprehensive methods for vault operations including search, batch operations, tag management, and frontmatter handling. Works with Claude, ChatGPT, and any MCP-compatible AI 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": {
  "mcp-obsidian": {
    "command": "npx",
    "args": ["-y","@bitbonsai/mcpvault@latest"]
  }
}
```

## Documentation

## What bitbonsai/mcp-obsidian does

bitbonsai/mcp-obsidian, published as MCPVault, gives MCP clients local access to an Obsidian vault. It can inspect and modify Markdown and other supported vault files while applying path restrictions around the configured vault root. Obsidian does not need to be open, and the setup does not depend on an Obsidian plugin.

The server supports note creation and editing, targeted text replacement, search, directory browsing, file moves, deletion, batch reads, and vault-level inspection. It also handles Obsidian-oriented structures such as YAML frontmatter, tags, and wiki links. Frontmatter updates preserve the formatting of fields that are not changed.

## How it works

An MCP client launches the server locally over stdio and supplies a vault path as a command-line argument. If no path is supplied, the current working directory becomes the vault root. The same MCP tools are available to each supported client rather than being tied to a particular AI provider.

Path validation prevents traversal outside the vault and blocks symlink escapes. Dotfiles and the `.obsidian`, `.git`, and `node_modules` directories are also restricted. Search and directory listing can be narrowed with repeated `--exclude` arguments; individual calls can add further exclusions. These listing exclusions do not prevent direct reads or writes to excluded paths.

A `--read-only` option removes mutating tools from discovery and rejects direct calls to them. Deletion and arbitrary file moves require confirmation paths. Search and batch results use compact fields by default, with `prettyPrint: true` available for expanded output.

## Setup and configuration

Node.js 20 or newer and a local Obsidian vault are required. The published package can be started with:

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

For a quick connection test, run it through MCP Inspector:

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

MCP clients configure the server as a local command using `npx`, the package name, and the vault path. Multiple vaults can be configured as separate server entries. Developers working from the repository can install dependencies with `npm install` and start the local implementation with `npm start`, optionally followed by a vault path.

## Tools and capabilities

- Read, create, overwrite, append to, prepend to, patch, move, and delete notes.
- Move or rename arbitrary files with binary-safe handling through `move_file`.
- List vault directories and read up to 10 notes in one batch operation.
- Search note content and frontmatter with multi-word matching and BM25 reranking.
- Inspect note metadata, vault statistics, frontmatter, and the complete set of tags.
- Add, remove, or list tags on individual notes.
- Resolve Obsidian wiki links, including display-text, path-qualified, and escaped forms; ambiguous matches include alternative paths.
- Retrieve a note outline and then read only a selected line range instead of loading the full note.

## Limitations and notes

The server is local and uses stdio, so the client must be able to launch local MCP processes. Its vault access is controlled by the path supplied at startup. Note-oriented operations target supported note files, while directory listing can include non-note filenames. Read-only mode is available when write access should be excluded from the client session. ChatGPT Desktop configuration requires an Enterprise, Education, or Team subscription according to the supported-client setup.

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