MCP Obsidian

What bitbonsai/mcp-obsidian MCP server does

The bitbonsai/mcp-obsidian MCP server exposes local Obsidian vault operations through the Model Context Protocol. It can read notes, create or replace content, append or prepend text, apply patches, delete files, move notes, and move other supported vault files. The server works directly with the vault directory rather than communicating through Obsidian itself.

It also provides tools for finding and inspecting content. Agents can list directories, read several notes at once, retrieve an outline or selected lines from a note, search notes, inspect frontmatter, review vault statistics, and work with tags. Wiki-link resolution can identify a note by name and report alternative paths when that name is ambiguous.

How it works

An MCP client launches the server as a local stdio process and supplies the vault path on the command line. The same MCP tool set is available to each compatible client, so the implementation does not depend on a particular AI provider. Obsidian does not need to be open, and no Obsidian plugin is required.

The configured directory becomes the vault root. Path validation blocks traversal outside that root and rejects symlink escapes, dotfiles, .obsidian, .git, and node_modules. Destructive operations add confirmation requirements: delete_note and move_file require matching confirmation paths. Frontmatter updates use AST-aware handling intended to preserve formatting for YAML fields that were not changed.

Setup and configuration

The bitbonsai/mcp-obsidian MCP server requires Node.js 20 or later, an Obsidian vault on the local filesystem, and an MCP-compatible client. The published package can be started with npx @bitbonsai/mcpvault@latest; adding a vault path selects that directory, while omitting the path uses the current working directory.

Client configuration passes the package name and vault path as the server command arguments. Multiple vaults can be configured as separate MCP server entries. A --read-only option exposes only read tools and rejects mutation requests; --read-only true and --read-only=true are also accepted.

The README provides configuration examples for 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. Other clients can use the server if they support local stdio MCP servers.

Tools and capabilities

The documented tool groups include:

• File changes: write_note, patch_note, delete_note, move_note, and move_file.
• Reading and navigation: read_note, get_note_outline, read_note_lines, list_directory, and read_multiple_notes.
• Discovery: search_notes, including multi-word matching and BM25 reranking.
• Metadata: get_frontmatter, update_frontmatter, get_notes_info, and get_vault_stats.
• Tags and links: manage_tags, list_all_tags, and wiki_link.

write_note supports overwrite, append, and prepend modes. Search and batch-read responses use compact fields by default, with prettyPrint: true available for expanded output. The package also publishes TypeScript declarations and public types.

Limitations and notes

This server is designed for local vault access, not a hosted or remote Obsidian service. The client must be able to start a local process and the vault must be available as a local directory. Supported vault files include .md, .markdown, .txt, .base, and .canvas files. Read-only mode prevents mutation tools from being discovered and rejects direct mutation calls; normal read/write behavior is enabled when the option is omitted or set to false.