Obsidian Mcp Server Community

Frequently asked questions

What does the Obsidian Mcp Server MCP server do?

Obsidian MCP A local Model Context Protocol server that lets MCP-compatible assistants safely read and modify explicitly configured Obsidian vaults. Version 2 supports both MCP 2026-07-28 and 2025-era clients by default, and requires Node.js 22 or newer. It works directly with Markdown files, so Obsidian does not need to be open. Legacy protocol and v1 positional-path compatibility are deprecated and print exact migration instructions to stderr. > [!IMPORTANT] > MCP clients can invoke destructive tools. Back up important vaults, review client permission prompts, and use revision preconditions for concurrently edited notes. Quick start Node.js 22 or newer is required: Run with npx without installing the package globally. Pinning the major version receives compatible 2.x updates without automatically crossing a future major version: Configure an MCP client to launch the same command over stdio: Alternatively, install the package globally and use "command": "obsidian-mcp" with the same arguments beginning at "serve" : Each vault must already contain an .obsidian directory and must be configured using an absolute path. Both protocol eras are served from the same tool definitions. After confirming that your MCP client negotiates 2026-07-28 , you may opt into modern-only mode by adding "--legacy", "reject" to args . Vault ids use lowercase letters, digits, , and - , must begin with a letter, and are the values assistants pass to tools. Up to ten vaults may be configured. Repeat --vault to expose more than one vault: Network, removable, hidden, and synced locations are allowed because an explicit --vault is treated as authorization; the same containment protections apply to every location. Design principles Vault access is explicitly allowlisted at process startup. Every tool path is vault-relative, segment-checked, and blocked from symlinks and reserved state. File mutations are journaled, conflict-checked, atomically replaced, and rolled back as one transaction. The server never listens on a network interface or sends telemetry. stdout is reserved exclusively for MCP messages; structured diagnostics go to stderr. Results are bounded, paginated where appropriate, and available as both text and structured content. Tools Tool Purpose --------------------------- ----------------------------------------------------------------------------- obsidian list vaults List configured vault ids without exposing host paths. obsidian read note Read a bounded page of a note and return its SHA-256 etag . obsidian create note Atomically create a note without overwriting. obsidian edit note Append, prepend, or replace exact note content. obsidian delete note Move a note to MCP trash or permanently delete it with explicit confirmation. obsidian move note Move or rename a note and update unambiguous backlinks transactionally. obsidian create directory Transactionally create a directory inside a vault. obsidian search vault Search content, filenames, or tags with bounded cursor pagination. obsidian add tags Add tags to one or more notes atomically. obsidian remove tags Remove exact, nested, or wildcard-selected tags atomically. obsidian rename tag Rename a tag across the vault atomically. obsidian manage tags Unified add/remove tag workflow using the same implementation. All schemas are strict JSON Schema 2020-12 contracts generated from Zod. Mutating results include a transaction id; tool failures return isError: true with an actionable error code. Reading and concurrency obsidian read note returns an etag . Pass it as if match to edit, move, or delete when avoiding lost updates matters. Batch tag operations accept an expected etags map. A changed note returns REVISION CONFLICT rather than being overwritten. Large notes are paginated using an opaque cursor bound to the path and etag . Search uses an opaque cursor bound to the query and options. Tool text responses are capped at 25,000 characters. Deletion and recovery Trash is the default. Deleted note bytes and metadata are stored separately under .obsidian-mcp/trash ; metadata is never injected into the note. Permanent deletion requires confirm path to exactly match the canonical relative path. Transactions and recovery snapshots live in .obsidian-mcp/transactions . Completed data is retained for 30 days and pruned oldest-first above 1 GiB by default: Inspect or restore a completed transaction while the MCP server is stopped: Recovery refuses to overwrite content changed since the selected transaction. Permanent deletion snapshots are purged after commit and cannot be restored. Path and filesystem safety The server: canonicalizes configured vault roots and rejects duplicate or nested roots; rejects absolute, UNC, Windows-drive, NUL, backslash, empty, and dot-segment tool paths; reserves .obsidian , .obsidian-mcp , .git , .backup , and .trash from tool access; checks existing targets and the nearest existing ancestor for new targets; rejects symlinks, junctions, and reparse-point paths, and skips them during scans; performs no shell execution for filesystem validation; strictly decodes UTF-8 and does not silently replace invalid bytes. The process needs read and write access to each configured vault. obsidian-mcp doctor --vault id=/path validates startup readiness and recovery state. Link and tag behavior Moves recognize Obsidian Wikilinks, embeds, Markdown links, aliases, URL-encoded destinations, headings, and block anchors. A link is rewritten only when it resolves unambiguously to the source note; ambiguous links are reported and left unchanged. Deletion preserves backlinks unless backlink action: "mark broken" is requested. Tags follow Obsidian's case-insensitive rules and support Unicode, emoji, , - , / , and nested tags. Frontmatter tags are written as YAML lists. Inline tag processing ignores fenced/inline code and HTML comments. Wildcards use a bounded matcher rather than regular expressions. Development Each tool owns a typed definition under src/tools/ >/index.ts ; the small registry in src/tools/index.ts applies shared MCP registration and response behavior. Filesystem, transaction, Markdown, link, and search behavior live in reusable utilities. A new tool must use VaultFs for every path, TransactionManager for mutations, strict input/output schemas, structured results, annotations, and security/integration tests. See MIGRATING.md for the 1.x migration and SECURITY.md for vulnerability reporting. Startup errors and compatibility warnings are written only to stderr with a stable code, the detected problem, an exact fix, a verification step, and a link to the matching migration section. If the server does not appear, find the code in the MCP client logs and use the diagnostic reference. License MIT

How do I install Obsidian Mcp Server?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is Obsidian Mcp Server free to use?

The MCP server itself is free to install. The source is public on https://github.com/StevenStavrakis/obsidian-mcp. Any third-party service it calls may require its own API key and account.

Which clients support Obsidian Mcp Server?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.