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 linksresult.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.<key>, 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 totalMatchesmode: "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 valueget 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 caller, the path, and the note's content then. A pre-supplied or replayed answer, or one given after the note changed, gets a fresh prompt instead
- Consent records live in the server's storage provider (
STORAGE_PROVIDER_TYPE, default in-memory, process-local). That works for stdio or a single HTTP instance; several instances behind one endpoint need a shared provider (filesystem, supabase, or cloudflare-d1, never cloudflare-kv)
obsidian_open_in_ui tool
path, failIfMissing (default true), and newLeaf (open in a split pane); with failIfMissing: false a missing file is created, which needs write accesscreatedIfMissing reports which branch ran- A case-mismatched
path with one case-insensitive match opens that file instead of creating another, reporting the path sent as requestedPath with a notice
obsidian_list_commands tool
- Optional
nameRegex (≤256 chars) matched against each command's display name
- Returns
commands[] of id and name, where id feeds obsidian_execute_command
- Listed only when
OBSIDIAN_ENABLE_COMMANDS=true and OBSIDIAN_READ_ONLY is off
obsidian_execute_command tool
commandId from obsidian_list_commands; returns executed: true, or fails with command_unknown for an unregistered ID- Runs with the authority of a keyboard shortcut, so some commands are destructive (delete file, close vault); gated like
obsidian_list_commands
obsidian://vault/{+path} resource
{+path} captures everything after /vault/, slashes included; literal and percent-encoded paths resolve to the same note- Returns
path, content, frontmatter, tags, and stat, the same shape as obsidian_get_note with format: "full"; failures are path_forbidden, note_missing, or path_is_directory
obsidian://tags resource
- Every tag with its
count, uncapped and unsorted, hierarchical parents included
- With
OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS set, only tags from readable notes, counted the same way as obsidian_list_tags
- No ranking or filters;
obsidian_list_tags gives the count-ranked, capped view
obsidian://status resource
status, service, authenticated, versions, manifest, and apiExtensions[]; still answers with a wrong API key, reporting authenticated: false- On plugin v5.0.2 and later, check
apiExtensions for local-rest-api-periodic-notes before using periodic targets
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Obsidian-specific:
- Typed client for the Obsidian Local REST API plugin; section writes speak markdown-patch 2.0 to plugin v5.0 and later and 1.x to v4.x, chosen from the reported plugin version
- Heading targets take a full
Parent::Child path or a bare leaf name; writes reject an ambiguous one with ambiguous_section and its candidates, unless exactly one match is a top-level heading. On plugin v5.0 and later, content added to a heading is set off by a blank line (a list item continues an adjacent list), and a heading inside it must sit below the section's level (heading_outside_section)
- Folder-scoped read/write permissions, a deny list that withholds paths from both, a read-only switch, and an opt-in command-palette pair (see Path policy); server-level
instructions on initialize report the active policy
obsidian_get_note and obsidian_open_in_ui retry a case-mismatched path against the real filename, disclosed as requestedPath plus a notice, and add Did you mean suggestions to a miss; writes and deletes match the exact path- Regex inputs are capped (
nameRegex at 256 chars, useRegex at 1024) and rejected with regex_unsafe when they nest quantifiers
- Backlinks have no dedicated tool;
obsidian_search_notes in jsonlogic mode finds them with {"regexp": ["\\[\\[Target Note(\\\\?\\||#|\\]\\])", {"var": "content"}]}, which also matches the table-safe [[Target Note\|Alias]]
Agent-friendly output:
- Recovery-guided errors: every declared failure carries a
reason, a JSON-RPC code, and a recovery.hint written for that case
- Size deltas: every mutating tool returns
previousSizeInBytes / currentSizeInBytes, so a caller can spot an accidental clobber without a follow-up read
- Ambiguity surfaced as data: shared heading names return
candidates, and tag operations report applied vs. skipped
- Discriminated output contracts:
format on obsidian_get_note, mode on obsidian_search_notes, operation on obsidian_manage_frontmatter and obsidian_manage_tags
Getting started
Add it to Claude Code:
For other clients, add this to the MCP config file:
Generate the key in Obsidian under Settings → Community Plugins → Local REST API, with the plugin set up as Prerequisites describes. For Docker or a source build, see Running the server.
Prerequisites
- The Obsidian Local REST API plugin, v4.0.0 or later, enabled in your vault. Its API key is
OBSIDIAN_API_KEY.
- The server defaults to
http://127.0.0.1:27123, so enable "Non-encrypted (HTTP) Server" in the plugin settings, or set OBSIDIAN_BASE_URL=https://127.0.0.1:27124 for the always-on HTTPS port (its self-signed cert is accepted while OBSIDIAN_VERIFY_SSL=false, the default).
- Periodic-note targets work natively on plugin v5.0.1 and earlier. From v5.0.2 they need the periodic-notes API extension; without it they fail with
periodic_unsupported.
- On plugin v4.x, heading section writes to a note with CRLF (Windows) line endings land mid-line: the plugin's markdown-patch 1.x engine misplaces them, and the server can't correct it. Plugin v5.0 and later handle CRLF notes.
- Plugin v6.0 drops markdown-patch 1.x, which two table-row writes (
contentType: "json") still use: rows under a heading, and rows through a block ID on its own line below the table. On v6.0, target the table by an ID on its last row.
- With
OBSIDIAN_DELETE_ELICITATION=true, an MCP client that supports elicitation and renders its form, to use obsidian_delete_note. Every other tool, and the default delete, works without it.
Configuration
See .env.example for the full list of optional overrides.
Path policy
Four optional env vars limit which vault paths the tools can touch. Unset, reads and writes cover the full vault.
- Matching is by prefix, recursive, and case-insensitive. Entries are normalized the way a path reaches the plugin:
\ becomes /, repeated and trailing slashes collapse, . segments drop, and names are compared in Unicode NFC, so journal//therapy and ./private cover the folders they name. Request paths get the same slash, case, and NFC folding, so notes//private/x.md or an NFD spelling of a denied name is refused like the plain one. An entry naming the vault root (., ./) fails startup. Write paths are also readable.
OBSIDIAN_DENY_PATHS wins over both allowlists, write-implies-read included: a denied path is neither readable nor writable, and it is left out of listings, search hits, and tag counts. An allow entry inside a deny entry grants nothing, and the startup log warns about it.OBSIDIAN_READ_ONLY=true removes every write tool and the command-palette pair from tools/list, including obsidian_manage_frontmatter and obsidian_manage_tags (so their get / list go too). obsidian_open_in_ui still opens existing files but won't create one.- A denial fails with
path_forbidden, echoing the active scope in data.activeScope and the recovery hint. A path the deny list withholds fails with subreason denied_path instead, which carries no activeScope and names OBSIDIAN_DENY_PATHS but none of its entries; a path outside an allowlist reports outside_read_paths or outside_write_paths even when it is also denied. A denial on an active or periodic target names the target ((active file), daily note for 2026-10-01), not the note it resolved to. obsidian_list_notes lists only readable entries plus the folders leading to the scope, so a nested scope can be browsed to from the root; a denied folder never appears, even on the way to an allow entry.
- Under
OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS, searches return readable notes only. With neither set, a JSONLogic tree goes to the plugin unchanged; with either:
- JSONLogic: the server evaluates the tree over the readable notes, so it never reads a note outside the scope. Notes carry no
links, backlinks, or unresolvedLinks, since Obsidian resolves a link across the whole vault: a tree naming one by a fixed var, missing, or missing_some key fails with link_fields_unavailable, and a computed key reads null. Match link text in content instead. A tree that names content reads each readable note with one request per note, at most 32 in flight across the server.
- Evaluation is bounded (1,000 levels of nesting, a work budget per note and per search, 10 s of evaluation, 45 s for the whole search); a tree past a bound fails with
logic_too_costly. A readable note nested too deep for the evaluator (about 3,500 levels under Node) fails the search with note_too_deep.
- Text: the server never calls the plugin's text search. It asks the plugin which readable notes may hold every token, reads each candidate note, and applies Obsidian's search rule itself, so hits and context windows match the unscoped search. Past 45 s it fails with
text_search_too_costly, and context_length_too_large fails where the plugin's response for the readable matches alone would pass its size ceiling.
- Omnisearch ranks the whole vault before the scope filters it (see
obsidian_search_notes).
- Tag listings (
obsidian_list_tags, obsidian://tags) under OBSIDIAN_READ_PATHS or OBSIDIAN_DENY_PATHS cover readable notes only, counting notes rather than occurrences. Write paths and read-only alone leave them vault-wide.
- The server
instructions state the effective scope: readable is the read paths plus the write paths, and writable is the write paths, or the read scope when only reads are restricted. With a deny list set, each scope reads "…, except paths the operator withholds", naming none of them, and an empty scope reads none. The startup log prints the configured lists, the deny list included.
Running the server
Local development
Requires Bun v1.4.0 or higher (or Node.js v24+).
Docker
The image defaults to HTTP transport on 0.0.0.0, stateful sessions, and logs in /var/log/obsidian-mcp-server. Inside a container, the default OBSIDIAN_BASE_URL (http://127.0.0.1:27123) is the container's own loopback: point it at http://host.docker.internal:27123 (Docker Desktop) or use --network host (Linux) to reach the plugin on your host. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "OBSIDIAN_API_KEY=your-key", "-e", "OBSIDIAN_BASE_URL=http://host.docker.internal:27123", "ghcr.io/cyanheads/obsidian-mcp-server:latest"]. To build locally, docker build -t obsidian-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
If the port is reachable from other machines, set MCP_AUTH_MODE=jwt (with MCP_AUTH_SECRET_KEY) or oauth. With the default none, every caller acts on your vault with your OBSIDIAN_API_KEY.
Project structure
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catch in tool logic
- Use
ctx.log for request-scoped logging; route every Local REST API call through getObsidianService()
- Register new tools and resources via the barrels in
src/mcp-server/*/definitions/index.ts
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Bugs, feature requests, and documentation gaps belong in an issue; see CONTRIBUTING.md for what makes one actionable and CODE_OF_CONDUCT.md for how we work together. Security reports go through SECURITY.md, never a public issue.
Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.
