StevenStavrakis/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. |