obsidian-mcp-server

obsidian-mcp-server Read, write, search, and surgically edit Obsidian vault notes, tags, and frontmatter via MCP. STDIO or Streamable HTTP. 14 Tools • 3 Resources

---

Overview

Obsidian vault notes over the Local REST API plugin. Read, search, and write notes, edit single headings, blocks, and frontmatter fields in place, and manage tags, with folder-scoped read/write permissions built in. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
obsidian_get_note	Read a note as raw content, full structured form, document map, or a single section
obsidian_list_notes	List notes and folders under a vault path, recursively, with extension and name filters
obsidian_list_tags	List vault tags with usage counts, most-used first
obsidian_search_notes	Search by text, JSONLogic, or BM25-ranked Omnisearch when that plugin is reachable
obsidian_write_note	Create a note, replace one section, or overwrite a whole file with overwrite: true
obsidian_append_to_note	Append to a note (creating it if missing) or to one heading, block, or frontmatter field
obsidian_patch_note	Append, prepend, or replace against one heading, block reference, or frontmatter field
obsidian_replace_in_note	Literal or regex search-replace inside one note, body-only by default
obsidian_manage_frontmatter	Get, set, or delete one frontmatter key
obsidian_manage_tags	Add, remove, or list a note's tags in frontmatter, inline, or both
obsidian_delete_note	Permanently delete a note, optionally after the user confirms (OBSIDIAN_DELETE_ELICITATION)
obsidian_open_in_ui	Open a file in the Obsidian app, optionally in a new pane
obsidian_list_commands	List command-palette commands (opt-in via OBSIDIAN_ENABLE_COMMANDS)
obsidian_execute_command	Run a command-palette command by ID (opt-in via OBSIDIAN_ENABLE_COMMANDS)

Resources

Resource	Description
obsidian://vault/{+path}	A note's content, frontmatter, tags, and file metadata
obsidian://tags	Every vault tag with its usage count, as an uncapped snapshot
obsidian://status	Plugin reachability, auth status, versions, and registered API extensions

Note and tag data are also reachable through tools (obsidian_get_note, obsidian_list_tags); obsidian://status has no tool equivalent.

Capability reference

obsidian_get_note tool

• target is a vault path, the active file, or a periodic note (daily through yearly, optional date); format is content, full, document-map, or section, and full takes includeLinks: true for vault-internal outgoing links
• result.format discriminates the payload; a section read that matches several headings returns the first and lists every full path in candidates
• A path with no exact match but one case-insensitive match in its folder reads that file: result.path is the real name, requestedPath the one sent, and a notice names both

---

obsidian_list_notes tool

• Walks from path (default vault root) to depth 1–20 (default 2), filtered by extension and nameRegex (≤256 chars); a folder that fails nameRegex is not walked
• Returns entries[] (file / directory), totals, and appliedFilters; the walk stops at 1,000 entries with excluded.reason: "entry_cap", and a folder the depth limit stopped carries truncated: true
• With OBSIDIAN_READ_PATHS set, a listing holds only readable entries and the folders leading to the scope; those folders are walked and accepted as path

---

obsidian_list_tags tool

• nameRegex (≤256 chars) and minCount narrow the set, then tags are ranked by count and capped at limit (default 200, max 10000); hierarchical parents count (work/tasks adds to work)
• When the cap withholds tags, the response carries truncated, shown, and cap
• With OBSIDIAN_READ_PATHS set, only tags from readable notes are listed, and count is the number of readable notes carrying the tag or a tag nested under it

---

obsidian_search_notes tool

• mode: "text" requires every whitespace-split token of query as a case-insensitive substring of the filename or body (quotes are literal), shaped by contextLength (default 100), pathPrefix, and maxMatchesPerHit (default 10); mode: "jsonlogic" evaluates a logic tree over path, content, frontmatter.<key>, tags, and stat, with glob / regexp taking [PATTERN, VALUE]
• result.mode discriminates the payload; every mode reports totalCount and pages via nextCursor, and a text hit clipped to maxMatchesPerHit carries truncated and totalMatches
• mode: "omnisearch" (BM25 ranking, quoted phrases, -exclusion, path: / ext: filters) is offered only when the Omnisearch plugin answered at startup; its 50-hit upstream cap sets truncated: true

---

obsidian_write_note tool

• target and content, with optional section and contentType (markdown / json); a whole-file write to an existing note fails with file_exists unless overwrite: true
• With section, replaces only that heading, block, or frontmatter field and keeps the heading line; output reports created, sectionTargeted, and the resolved sectionTarget

---

obsidian_append_to_note tool

• Without section, appends to the file or creates it (created: true); with section, appends to that heading, block, or frontmatter field of an existing note, and createTargetIfMissing: true creates the section
• A section append whose content is already at the target fails with content_preexists; block targets add no separator, so start content with a newline if you want one

---

obsidian_patch_note tool

• operation: "append" | "prepend" | "replace" against one section of an existing note; patchOptions takes createTargetIfMissing, `applyIfContentPree