Obsidian Vault

Overview

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

Tools

Resources

Vault-note and tag data are also reachable via tools — obsidian_get_note for obsidian://vault/{+path}, obsidian_list_tags for obsidian://tags (count-ranked and capped, unlike the resource's raw snapshot). obsidian://status has no tool equivalent. Resources exist for clients that prefer attaching a note or vault snapshot to a conversation.

Capability reference

obsidian_get_note tool

• format: "content" | "full" | "document-map" | "section" selects the projection; full accepts includeLinks: true for outgoing wiki/markdown links (vault-internal only — external URLs are filtered)
• Addressed by vault path, the active file, or a periodic note (daily / weekly / monthly / quarterly / yearly)
• Heading sections use Parent::Child syntax; a bare leaf name matching several headings returns the first match and lists every colliding path in candidates
• Forgiving path resolution: a case-mismatched path retries against the canonical filename, an ambiguous case match fails with Conflict, and a NotFound carries Did you mean: …? suggestions when near-matches exist
• Typed errors include note_missing, path_forbidden, no_active_file, periodic_unsupported / periodic_disabled, and path_traversal

obsidian_list_notes tool

• Recursive walk from path (default vault root); depth 1–20 (default 2 = target plus immediate children)
• Optional extension and nameRegex (≤256 chars, no nested quantifiers) filters; a directory failing nameRegex is skipped without recursing into it
• Hard cap of 1000 entries per call — excluded.reason: "entry_cap" signals a truncated walk; narrow path or the filters to see the rest
• Per-directory truncated: true marks entries cut off by the depth limit or by path policy

obsidian_list_tags tool

• Vault-wide tag counts, including hierarchical parents (work/tasks contributes to both work and work/tasks)
• Ordered by count descending, capped at limit (default 200, max 10000); optional nameRegex and minCount narrow the candidate set before ranking
• Reports truncated / shown / cap when the limit withheld results
• Not narrowed by OBSIDIAN_READ_PATHS — tag names (never note contents) can surface from outside the read scope

obsidian_list_commands tool

• Lists Obsidian command-palette IDs and display names; optional nameRegex filters on display name
• Opt-in via OBSIDIAN_ENABLE_COMMANDS=true — absent from tools/list when unset
• Discovery partner for obsidian_execute_command

obsidian_search_notes tool

• mode: "text" | "jsonlogic" always; "omnisearch" is added to the schema only when the Omnisearch plugin's HTTP server is reachable at startup (restart to re-probe)
• text — substring match with contextLength-sized context windows (default 100) and an optional pathPrefix; jsonlogic — a JSONLogic tree with var paths into path / content / frontmatter.<key> / tags / stat.{ctime,mtime,size}, plus glob / regexp operators taking [PATTERN, VALUE]; omnisearch — BM25-ranked, quoted phrases, -exclusion, path: / ext: filters, typo tolerance, PDF/OCR via Text Extractor, hard-capped at 50 upstream hits (truncated: true when likely hit)
• Cursor pagination — omit cursor for page one, pass nextCursor from the prior response; text-mode hits additionally clip to maxMatchesPerHit (default 10), flagged with truncated / totalMatches
• No dedicated backlinks tool — express "what links here" via jsonlogic: {"regexp": ["\\[\\[Target Note(\\||#|\\]\\])", {"var": "content"}]}

obsidian_write_note tool

• Without section — full-file write; refuses to clobber an existing note unless overwrite: true (file_exists conflict otherwise, naming the surgical-edit tools as the alternative)
• With section — PATCH-with-replace against a heading/block/frontmatter target, leaving the rest of the file untouched (overwrite is ignored); a bare heading leaf shared by several headings fails with ambiguous_section
• Output reports created, plus previousSizeInBytes / currentSizeInBytes on every call to spot an accidental clobber or a mistyped path

obsidian_append_to_note tool

• Without section — appends to an existing file, or creates it with the given content as the whole body (created: true flags the second case)
• With section — appends to a heading/block/frontmatter target; the file must already exist, and createTargetIfMissing: true brings the section itself into existence
• Block-reference targets concatenate with no separator — include a leading newline in content for one
• previousSizeInBytes / currentSizeInBytes bracket every call for drift detection

obsidian_patch_note tool

• operation: "append" | "prepend" | "replace" against one heading, block reference, or frontmatter field per call
• Heading targets accept the full Parent::Child path or an unambiguous bare leaf name; a leaf matching several headings fails with ambiguous_section and lists the candidates
• patchOptions: createTargetIfMissing, applyIfContentPreexists (idempotency guard — otherwise content_preexists), trimTargetWhitespace

obsidian_replace_in_note tool

• One or more replacements, applied in array order, each over the previous one's output
• scope: "body" (default, frontmatter left byte-identical) | "frontmatter" | "both"; frontmatter/both re-parse the rewritten YAML afterward and write nothing if it breaks (frontmatter_invalid)
• Per-replacement options: useRegex (≤1024 chars, no nested quantifiers), caseSensitive, wholeWord (\b…\b in both modes), flexibleWhitespace (literal mode only), replaceAll (default true)
• perReplacement[] reports bodyCount / frontmatterCount per entry; totalReplacements sums them

obsidian_manage_frontmatter tool

• operation: "get" | "set" | "delete" on a single frontmatter key; set requires a JSON-typed value (string, number, boolean, array, or object)
• get needs read access; set / delete need the path inside OBSIDIAN_WRITE_PATHS with OBSIDIAN_READ_ONLY=false
• set / delete return the full frontmatter after the change plus previousSizeInBytes / currentSizeInBytes

obsidian_manage_tags tool

• operation: "add" | "remove" | "list"; location: "frontmatter" (default, canonical tags: array) | "inline" (body #tag, add appends at end-of-file) | "both" (reconciles both)
• Inline detection skips fenced/inline code spans, link spans ([[...]], [text](...), [text][ref]), and \#-escaped hashes, so a heading anchor or wikilink alias is never mistaken for a tag
• add / remove report applied vs. skipped tags plus the full tags set after the change; list ignores the input tags array

obsidian_delete_note tool

• Always asks for confirmation first — the initial call returns an elicitation request naming the file's byte size, and is retried with the answer; declining fails with cancelled and issues no DELETE
• No API-level undo — recovery requires Obsidian's local trash
• Requires an MCP client that can serve an elicitation round-trip; every other tool works without one

obsidian_open_in_ui tool

• failIfMissing (default true) controls open-vs-create: opening an existing file needs read access, opening a missing one (with failIfMissing: false) creates it and needs write access
• newLeaf opens in a split pane instead of the active one
• Same forgiving path resolution as obsidian_get_note (case fallback, Did you mean suggestions); obsidian_delete_note deliberately doesn't get it — a destructive op never silently rewrites its target
• Output reports createdIfMissing so the caller can tell which branch ran

obsidian_execute_command tool

• Dispatches an Obsidian command-palette command by commandId (discover via obsidian_list_commands); runs with the same authority as a keyboard invocation
• Opt-in via OBSIDIAN_ENABLE_COMMANDS=true — absent from tools/list when unset
• Behavior is command-dependent — some are destructive (delete file, close vault), some open UI

obsidian://vault/{+path} resource

• The {+path} segment captures everything after /vault/, including slashes
• Paths may be sent literally or percent-encoded — Folder/Test Note.md and Folder/Test%20Note.md resolve to the same note, as do non-ASCII names and a bare %
• Returns the same shape as obsidian_get_note with format: "full" — content, frontmatter, tags, stat
• Gated by OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS like the tool equivalent

obsidian://tags resource

• Full snapshot of the upstream /tags/ payload — unsorted, uncapped, includes hierarchical parents
• Not a mirror of obsidian_list_tags: no count-descending order, no limit / nameRegex / minCount

obsidian://status resource

• Reachability, plugin version, authenticated (whether the configured OBSIDIAN_API_KEY was accepted), and plugin manifest info
• apiExtensions[] lists registered plugin extensions — check for local-rest-api-periodic-notes before relying on periodic targets on plugin v5.0.2 and later
• Still reports reachability when the API key is misconfigured; only authenticated reflects the key's validity

Path policy (folder-scoped permissions)

Three optional env vars gate which vault paths each tool can target. Default unset = full vault for both reads and writes — backwards compatible.

Matching is prefix-based with implicit recursion, case-insensitive, with trailing slashes normalized. projects/ matches projects/a.md, projects/sub/b.md, etc.

Write paths are implicitly readable — you can't sanely edit what you can't see. So a read passes when the target matches READ_PATHS or WRITE_PATHS.

OBSIDIAN_READ_ONLY=true short-circuits before the path checks — every write tool and the command-palette pair are wrapped with disabledTool() at startup (absent from tools/list), and any write that still reaches the service is denied at runtime regardless of WRITE_PATHS.

Denies are typed path_forbidden (JSON-RPC code Forbidden) with the active scope echoed back in data.recovery.hint and data.activeScope, so the LLM can self-correct without inspecting server logs. Search results from obsidian_search_notes are filtered against READ_PATHS silently — surfacing a "we hid N hits" indicator would defeat the gate.

Tag listing is vault-wide. obsidian_list_tags and the obsidian://tags resource aggregate tag names across the whole vault and are not narrowed by OBSIDIAN_READ_PATHS — they take no path to gate, so tag names (never note contents) from outside the read scope can surface.

The startup banner logs the active scope so operators can verify their config at boot.

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:

• Wraps the Obsidian Local REST API plugin — typed client, deterministic error mapping
• Section-aware editing across headings, block references, and frontmatter fields via PATCH-with-target operations
• Search across three modes — text, JSONLogic, and (when reachable) BM25-ranked Omnisearch — cursor-paginated per the MCP 2025-11-25 spec
• Tag reconciliation across both representations: frontmatter tags: array and inline #tag syntax
• Folder-scoped read/write permissions via OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS and a global OBSIDIAN_READ_ONLY kill switch; opt-in command-palette pair gated by OBSIDIAN_ENABLE_COMMANDS. Server-level instructions on initialize report the active policy to the caller

Agent-friendly output:

• Recovery-guided errors — every declared failure carries a reason, a JSON-RPC code, and a recovery.hint written for that case, so a rejection names what to do next instead of only what broke
• Size-delta self-correction — every mutating tool returns previousSizeInBytes / currentSizeInBytes, so a caller can spot an accidental clobber or unexpected upstream behavior without a follow-up read
• Ambiguity surfaced structurally — a heading leaf name shared by several headings returns candidates instead of silently picking one; tag operations report applied vs. skipped so a caller sees exactly what changed
• Discriminated output contracts — format on obsidian_get_note, operation on obsidian_manage_frontmatter and obsidian_manage_tags, mode on obsidian_search_notes — callers branch on typed fields instead of parsing text

Getting started

Add the following to your MCP client configuration file. The Obsidian Local REST API plugin must be installed and enabled in your vault — see Prerequisites.

jsonCopy code
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

jsonCopy code
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "obsidian-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "OBSIDIAN_API_KEY": "your-local-rest-api-key"
      }
    }
  }
}

Or with Docker:

jsonCopy code
{
  "mcpServers": {
    "obsidian-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "MCP_LOG_LEVEL=info",
        "-e", "OBSIDIAN_API_KEY=your-local-rest-api-key",
        "ghcr.io/cyanheads/obsidian-mcp-server:latest"
      ]
    }
  }
}

The default OBSIDIAN_BASE_URL (http://127.0.0.1:27123) points at the container's own loopback, not your host — add -e OBSIDIAN_BASE_URL=http://host.docker.internal:27123 (Docker Desktop) or run with --network host (Linux) so the container can reach the plugin.

For Streamable HTTP, set the transport and start the server. Inline env vars work for one-off runs; for repeated use, copy values into .env (see .env.example) and run bun run start:http.

shCopy code
MCP_TRANSPORT_TYPE=http OBSIDIAN_API_KEY=... bun run start:http
# Server listens at http://127.0.0.1:3010/mcp by default

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• The Obsidian Local REST API plugin, v4.0.0 through v5.x, installed and enabled in your vault. Generate an API key in Settings → Community Plugins → Local REST API and copy it into OBSIDIAN_API_KEY. Plugin v6.0 removes the markdown-patch 1.x wire format this server pins for section-targeted writes and the document map.
• Periodic-note targets (target: { "type": "periodic" }) work across that whole range: natively on plugin v5.0.1 and earlier, and on v5.0.2 and later — which moved the /periodic/ routes out of the plugin — once the companion periodic-notes API extension is installed. Without that extension on v5.0.2+, periodic targets fail with a periodic_unsupported error naming it; obsidian://status lists the registered extensions if you want to check first. Every other target type is unaffected.
• An MCP client that can answer an input request (elicitation). obsidian_delete_note always asks for confirmation before deleting, so a client without that support can read and write notes but cannot delete one.
• This server defaults to http://127.0.0.1:27123 for simplicity. Enable "Non-encrypted (HTTP) Server" in the plugin settings to use it. To use the always-on HTTPS port instead, set OBSIDIAN_BASE_URL=https://127.0.0.1:27124; the plugin's self-signed cert is handled by OBSIDIAN_VERIFY_SSL=false (the default), which relaxes verification for this server's requests to that endpoint only.

Installation

1. Clone the repository:

   shCopy code
   git clone https://github.com/cyanheads/obsidian-mcp-server.git
   

2. Navigate into the directory:

   shCopy code
   cd obsidian-mcp-server
   

3. Install dependencies:

   shCopy code
   bun install
   

4. Configure environment:

   shCopy code
   cp .env.example .env
   # edit .env and set OBSIDIAN_API_KEY
   

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run the production version:

  shCopy code
  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  shCopy code
  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

shCopy code
docker build -t obsidian-mcp-server .
docker run --rm -e OBSIDIAN_API_KEY=your-key -p 3010:3010 obsidian-mcp-server

The Dockerfile defaults to HTTP transport, stateful session mode (required for the obsidian_delete_note confirmation round), and logs to /var/log/obsidian-mcp-server. Point OBSIDIAN_BASE_URL at http://host.docker.internal:27123 (Docker Desktop) or run with --network host (Linux) so the container reaches the plugin on your host. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

The image binds to 0.0.0.0 inside the container (required for Docker port mapping). For any deployment reachable beyond your own machine, set MCP_AUTH_MODE=jwt (with MCP_AUTH_SECRET_KEY) or oauth — otherwise the listener forwards your OBSIDIAN_API_KEY to the vault on behalf of every caller.

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, ctx.state for tenant-scoped storage
• 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:

shCopy code
bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.