obsidian_list_vaultsLABSCO SUMMARY
Written like someone expected an assistant to get it wrong: etags, journalled writes, and a trash that is not deletion.
File mutations are journalled, conflict-checked, atomically replaced and rolled back as one transaction, which matters in a vault that Obsidian sync may be touching at the same time. The etag flow is the part to actually use: read a note, pass its etag back on the edit, and a concurrent change becomes an error rather than a silent overwrite. The project's own warning still stands — clients can invoke destructive tools, so back the vault up before pointing an agent at it.
What it is
A local server over one or more Obsidian vaults you name at startup. It works directly with the Markdown files, so Obsidian does not have to be running, and every path is vault-relative and checked.
What you get
- The configured vault ids listed without exposing host paths — obsidian_list_vaults
- A note read as a bounded page, returned with a SHA-256 etag you can hold on to — obsidian_read_note
- Notes created without overwriting, edited by append, prepend or exact replacement, and directories created transactionally — obsidian_create_note, obsidian_edit_note, obsidian_create_directory
- Notes moved or renamed with unambiguous backlinks updated in the same transaction — obsidian_move_note
- Deletion to MCP trash, or permanent deletion when you confirm it explicitly — obsidian_delete_note
- Search over content, filenames or tags with bounded cursor pagination — obsidian_search_vault
- Tags added, removed by exact, nested or wildcard match, renamed across the whole vault, or handled through one unified workflow — obsidian_add_tags, obsidian_remove_tags, obsidian_rename_tag, obsidian_manage_tags
- Revision safety throughout: pass the etag as if_match on an edit, move or delete and a note changed underneath you returns REVISION_CONFLICT instead of being overwritten
- Bounded results everywhere — text responses capped at 25,000 characters, large notes paginated by an opaque cursor tied to the path and etag
Requirements
Node.js 22 or newer, and at least one vault given as an absolute path at launch: npx -y obsidian-mcp@2 serve --vault notes=<YOUR_NOTES>. Each vault must already contain an .obsidian directory, ids are lowercase and start with a letter, and up to ten can be configured by repeating --vault. Nothing else is reachable — access is allowlisted at process start, symlinks and reserved state are blocked, the server never listens on a network interface, and it sends no telemetry. Both the 2026-07-28 protocol era and 2025-era clients are served from the same tool definitions; adding --legacy reject makes it modern-only.
Setup effort
One command — npx -y obsidian-mcp@2 serve --vault notes=<YOUR_NOTES>
USE CASES
01
Finding the note that covers something you half remember
Search content, filenames and tags together, and page through the results without flooding the context.
02
Adding to a note that you may also be editing in Obsidian
Read it for the etag, then pass that etag on the edit so a concurrent change is refused rather than lost.
03
Reorganising a vault without breaking links
Move or rename the note and let unambiguous backlinks update in the same transaction.
04
Cleaning up a tag scheme that grew organically
Rename a tag across the vault, or strip nested and wildcard-matched tags from the notes carrying them.
05
Capturing something into the right place from a conversation
Create the directory if it does not exist, then create the note without risking an overwrite.
06
Keeping an agent out of your other vaults
Name only the vault it should touch at launch and check what it can see before working.
12 tools
Listed in project docs. Your client may show a different list.
obsidian_read_noteobsidian_create_noteobsidian_edit_noteobsidian_delete_noteobsidian_move_noteobsidian_create_directoryobsidian_search_vaultobsidian_add_tagsobsidian_remove_tagsobsidian_rename_tagobsidian_manage_tagsBEFORE YOU INSTALL
What to know first
Tools you get
12 tools named in the project's documentation.
Requires
- npm on PATH
- Node.js 22 or later
INSTALLATION
Connect your client
Server setup
Configuration file
JSON
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"-y",
"obsidian-mcp@2",
"serve",
"--vault",
"notes=<YOUR_NOTES>"
]
}
}
}<YOUR_NOTES> is the absolute path to your Obsidian vault. The vault must already contain an .obsidian directory. notes is the vault id the assistant uses — repeat --vault id=/path to add more vaults.
npx
TERMINAL
npx -y obsidian-mcp@2 serve --vault notes=<YOUR_NOTES>
