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

Your Obsidian vault, through the Local REST API plugin. Read, search, and write notes, edit a single heading, block, or frontmatter field in place, and manage tags, with folder-scoped read/write permissions built in.

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 or OBSIDIAN_DENY_PATHS set, a listing holds only readable entries and the folders leading to the scope; those folders are walked and accepted as path, and a denied folder is absent at every depth

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 or OBSIDIAN_DENY_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 space-separated 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. , tags, and stat (plus links, backlinks, and unresolvedLinks on plugin versions that provide them, and not under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS), 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. It keeps its top 50 hits; path:, ext:, and plain terms apply before that cap, quoted phrases and -exclusion after it. truncated: true marks a result the cap may have cut, with truncatedReason cap_reached, filtered_after_cap, or read_scope; under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS it is always true, and a hit's membership and score still depend on the whole vault

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
• On a case-insensitive filesystem (macOS, Windows), a whole-file write to a path that differs from an existing note only in letter case fails with case_variant_exists and writes nothing; existingPath names that note when the parent folder's listing shows exactly one case match, and is omitted when several match or when a file Obsidian does not index (a dot-file) sits at the path
• 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
• A whole-file append to a path that differs from an existing note only in letter case fails with case_variant_exists on a case-insensitive filesystem, with existingPath naming that note when the parent folder's listing shows exactly one case match

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
• The path must match exactly, letter case included, even on a case-insensitive filesystem. A different-case or extension-less spelling fails note_missing before anything is deleted, naming the near matches in suggestions
• By default the note is deleted on the first call, with no confirmation; OBSIDIAN_WRITE_PATHS, OBSIDIAN_DENY_PATHS, and OBSIDIAN_READ_ONLY bound what it can reach
• With OBSIDIAN_DELETE_ELICITATION=true, the first call answers with a confirmation request naming the path and byte size, and the note is deleted only after the user accepts. Declining fails with cancelled, and a client without elicitation support cannot delete
• In that mode an answer counts only against the single-use consent record stored when the prompt was shown, bound to the c