Log inSubmit server
MCP Obsidian logo

MCP Obsidian

by bitbonsai

Local stdio MCP access to an Obsidian vault for reading, searching, editing, metadata, tags, and file management.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Obsidian

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "bitbonsai-mcp-obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "@bitbonsai/mcpvault@latest"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

bitbonsai/mcp-obsidian connects MCP-compatible AI clients to a local Obsidian vault through a Node.js stdio process. It exposes tools for reading, writing, searching, patching, moving, and deleting notes, along with metadata, frontmatter, tags, wiki links, and partial-reading operations. The server works directly with vault files, without an Obsidian plugin or a running Obsidian application, and confines access to the configured vault root. Reach for it when an agent needs controlled access to a local knowledge base or when large notes require outline and line-range reads.

Use cases

  • Read and update notes from an AI client
  • Search a vault by content or frontmatter
  • Organize notes with tags and frontmatter
  • Navigate large notes with outlines and line ranges
  • Review vault size, files, and recently modified content

Key features

  • Local stdio access to an Obsidian vault
  • Note and file read/write operations
  • Content and frontmatter search with BM25 reranking
  • Frontmatter, tag, wiki-link, and metadata tools
  • Batch reads and partial note retrieval
  • Read-only mode and vault path restrictions

Tools18

What MCP Obsidian lets your agent do. Expand a tool for its parameters.

Verified live~2.4k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

27/27 checks healthy over the last 77d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 2Low 0

Scanned 17d ago via OSV.dev · @bitbonsai/mcpvault@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1.7kStargazers on the source repository.
npm downloads47kPackage downloads in the last 30 days.
Last commitTodayMost recent push to the default branch.
Tools exposed18Callable tools this server registers over MCP.
Directory activity12 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Obsidian works

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:

Terminal
npx @bitbonsai/mcpvault@latest /path/to/your/obsidian/vault

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

Terminal
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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Obsidian

bitbonsai/mcp-obsidian is an MCP server that connects AI clients to a local Obsidian vault over stdio. Its main tools read, write, search, patch, move, and delete notes, while also supporting frontmatter, tags, wiki links, metadata, directory listing, batch reads, and partial line-based note access.

Install it by running `npx @bitbonsai/mcpvault@latest /path/to/your/vault` with Node.js 20 or later. Add the same command and vault path to your MCP client configuration. You can test the connection first with MCP Inspector.

Yes, Cursor is listed as a supported client. Configure it to launch the package as a local stdio MCP server and pass the path to the Obsidian vault as an argument.

Yes, add `--read-only` after the vault path. The server omits mutating tools from discovery and rejects direct calls to those tools, leaving the session with read-oriented access.

Pass one or more `--exclude <subtree>` arguments when starting the server. These defaults apply to search and directory listing across sessions, while per-call exclusions can add more paths.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Obsidian AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/bitbonsai-mcp-obsidian?style=directory)](https://allmcps.com/mcp/bitbonsai-mcp-obsidian)
HTML Embed
<a href="https://allmcps.com/mcp/bitbonsai-mcp-obsidian"><img src="https://allmcps.com/api/badge/bitbonsai-mcp-obsidian?style=directory" alt="MCP Obsidian on AllMCPs" /></a>