Obsidian Mcp Server

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

Resources

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, applyIfContentPreexists, and trimTargetWhitespace (plugin v4.x only)
• Echoes the resolved section and operation; a repeat of content already at the target fails with content_preexists unless applyIfContentPreexists: true

obsidian_replace_in_note tool

• replacements[] run in order, each over the previous one's output; each takes useRegex (≤1024 chars), caseSensitive (default true), wholeWord, flexibleWhitespace (literal mode only), and replaceAll (default true)
• Returns totalReplacements and perReplacement[] with bodyCount / frontmatterCount
• scope: "body" (default) leaves frontmatter byte-identical; "frontmatter" and "both" re-parse the YAML afterward and write nothing if it breaks (frontmatter_invalid)

obsidian_manage_frontmatter tool

• operation: "get" | "set" | "delete" on one key; set requires a JSON-typed value
• get returns exists and value (null when absent); set and delete return the full frontmatter after the change, and a delete against unparseable YAML fails with frontmatter_invalid without writing

obsidian_manage_tags tool

• operation: "add" | "remove" | "list" with tags; location: "frontmatter" (default, the tags: array), "inline" (body #tag; add appends at end of file), or "both"
• add / remove report applied, skipped, and the resulting tags; list returns frontmatter, inline, and all
• Inline detection follows Obsidian's tag grammar: code, wikilinks, images, link destinations, HTML, and math are skipped, and %% … %% comments are read

obsidian_delete_note tool

• Takes a target (path, active file, or periodic note) and checks it against the write scope first; a folder path fails with path_is_directory. There is no API-level undo, only Obsidian's local trash