---

Tools

Fourteen tools grouped by shape — readers fetch notes and metadata, writers create or surgically edit content, managers reconcile tags and frontmatter, and a guarded escape hatch dispatches Obsidian command-palette commands.

Tool Name	Description
obsidian_get_note	Read a note as raw content, full structured form (content + frontmatter + tags + stat), structural document map, or a single section.
obsidian_list_notes	List notes and subdirectories at a vault path with a recursive walk (default depth 2 — structural overview; max 20) bounded by a 1000-entry cap. Optional extension and nameRegex filters apply across the tree; regex-filtered directories are skipped without recursing into them. Returns flat entries[] plus a box-drawing tree in the rendered output; per-directory truncated: true flags where the depth limit cut off recursion.
obsidian_list_tags	List every tag found across the vault with usage counts, including hierarchical parents.
obsidian_list_commands	List Obsidian command-palette commands available for execution. Opt-in via OBSIDIAN_ENABLE_COMMANDS=true (paired with obsidian_execute_command).
obsidian_search_notes	Search the vault by text, Dataview DQL, or JSONLogic — capped at 100 hits with overflow indicator.
obsidian_write_note	Create a note, replace a single section in place, or — with overwrite: true — clobber an existing file. Refuses whole-file writes against an existing path by default.
obsidian_append_to_note	Append content to a note, or to a specific heading/block/frontmatter section.
obsidian_patch_note	Surgical append / prepend / replace against a heading, block reference, or frontmatter field.
obsidian_replace_in_note	Body-wide search-replace inside a single note. Literal or regex matching, with wholeWord, flexibleWhitespace, caseSensitive, replaceAll, and $1/$& capture groups.
obsidian_manage_frontmatter	Atomic get / set / delete on a single frontmatter key.
obsidian_manage_tags	Add, remove, or list tags — reconciles frontmatter tags: and inline #tag syntax.
obsidian_delete_note	Permanently delete a note. Elicits human confirmation when the client supports it.
obsidian_open_in_ui	Open a file in the Obsidian app UI, with failIfMissing and newLeaf toggles.
obsidian_execute_command	Execute an Obsidian command-palette command by ID. Opt-in via OBSIDIAN_ENABLE_COMMANDS=true.

obsidian_get_note

Read a note in one of four projections, addressed by vault path, the active file, or a periodic note (daily, weekly, monthly, quarterly, yearly).

• format: "content" — raw markdown body
• format: "full" — content, frontmatter, tags, and file metadata
• format: "document-map" — catalog of headings, block references, and frontmatter fields
• format: "section" — single heading/block/frontmatter section value (requires section); heading sections include the full subtree under that heading

Pair the document-map projection with obsidian_patch_note to discover edit targets before patching.

---

obsidian_search_notes

Three search modes selected by mode:

• text — substring match with surrounding context windows; optional pathPrefix filter (text mode only — passing pathPrefix in dataview or jsonlogic mode is rejected with path_prefix_invalid_mode)
• dataview — Dataview DQL (TABLE …) for path/date/metadata queries; file.mtime, file.path, etc. are queryable
• jsonlogic — JSONLogic tree evaluated against path, content, frontmatter.<key>, tags, and stat.{ctime,mtime,size}; custom glob and regexp operators

Results are capped at 100 hits. When the upstream returns more, an excluded indicator surfaces the overflow count and a hint to narrow the query. Text-mode hits are additionally clipped per file at maxMatchesPerHit (default 10) so a single match-heavy note can't blow the response budget — clipped hits carry truncated: true and totalMatches.

---

obsidian_write_note

Create or surgically replace, with a protective default against accidental whole-file overwrites.

• Without section — full-file PUT. Refuses to clobber an existing file unless overwrite: true is set. The file_exists (Conflict) error suggests obsidian_patch_note / obsidian_append_to_note / obsidian_replace_in_note for in-place edits.
• With section — PATCH-with-replace against the named heading/block/frontmatter field, leaving the rest of the file untouched. The overwrite flag is ignored in section mode.

The output reports created: true when the call brought a new file into existence; false when it replaced an existing one or targeted a section.

---

obsidian_patch_note

Surgical edits at a single document target.

• operation: "append" adds after the section
• operation: "prepend" adds before the section
• operation: "replace" swaps it out
• Targets: heading path, block reference ID, or frontmatter field

Use obsidian_get_note with format: "document-map" to discover what targets exist before patching.

---

obsidian_replace_in_note

Body-wide search-replace for edits that don't fit obsidian_patch_note's structural targets. The note is fetched, replacements are applied sequentially (each sees the previous output), and the result is written back in a single PUT.

Per-replacement options:

• useRegex — treat search as an ECMAScript regex. With useRegex: true, the replacement honors $1 / $& capture-group references.
• caseSensitive — when false, match case-insensitively
• wholeWord — wrap the pattern in \b…\b; works in both literal and regex modes
• flexibleWhitespace — substitute any run of whitespace in search with \s+. Literal mode only — has no effect when useRegex: true (express it directly).
• replaceAll — when false, only the first match is replaced

Literal mode preserves $1 / $& in the replacement verbatim — only useRegex: true expands capture-group references.

---

obsidian_manage_tags

Add, remove, or list tags on a note. Reconciles both representations:

• Frontmatter tags: array
• Inline #tag syntax in the body

add ensures the tag is present in the requested location(s); remove strips it. Inline #tag occurrences inside fenced code blocks are intentionally left alone.

---

obsidian_delete_note

Permanently delete a note. When the client supports elicit, the server requests human confirmation before issuing the DELETE. Without elicitation, the destructiveHint annotation surfaces the operation in the host's approval flow.

---

obsidian_execute_command

Dispatch an Obsidian command-palette command by ID (discoverable via obsidian_list_commands). Behavior is command-dependent — some commands open UI, others delete files or close the vault.

Off by default. Both obsidian_execute_command and its discovery partner obsidian_list_commands register only when the operator sets OBSIDIAN_ENABLE_COMMANDS=true; both are omitted from the surface otherwise.

---

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.

Goal	Config
Default (current behavior)	all unset
Read everywhere, write only in projects/ and scratch/	OBSIDIAN_WRITE_PATHS=projects/,scratch/
Read only public/, write only public/inbox/	OBSIDIAN_READ_PATHS=public/, OBSIDIAN_WRITE_PATHS=public/inbox/
Read-only deployment — no writes anywhere	OBSIDIAN_READ_ONLY=true

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 is denied regardless of WRITE_PATHS, and the command-palette pair is unregistered regardless of OBSIDIAN_ENABLE_COMMANDS (commands can mutate).

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.

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

---

Resources

Type	URI	Description
Resource	obsidian://vault/{+path}	A note in the vault — content, frontmatter, tags, and file metadata.
Resource	obsidian://tags	All tags found across the vault, with usage counts.
Resource	obsidian://status	Server reachability, plugin version, and auth status of the Obsidian Local REST API.

All resource data is also reachable via tools — obsidian_get_note for obsidian://vault/{+path}, obsidian_list_tags for obsidian://tags. Resources exist for clients that prefer attaching a specific note or vault snapshot to a conversation.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats. Tools advertise their failure surface via typed errors[] contracts.
• Pluggable auth on the HTTP transport: none, jwt, oauth
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

The server itself is stateless — every tool call hits the Local REST API directly. The framework's storage backends, request-state KV, and progress streams aren't used here; Obsidian is single-vault and there's nothing to persist between calls.

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
• Tag reconciliation across both representations: frontmatter tags: array and inline #tag syntax (skipping fenced code blocks)
• Search across three modes: text, Dataview DQL, JSONLogic — with overflow indicator when results exceed the 100-hit cap
• Optional human-in-the-loop confirmation for destructive deletes via ctx.elicit
• Folder-scoped read/write permissions via OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS and a global OBSIDIAN_READ_ONLY kill switch — denies are typed path_forbidden with the active scope echoed back in the error data
• Opt-in command-palette pair (obsidian_list_commands + obsidian_execute_command) — registered only when OBSIDIAN_ENABLE_COMMANDS=true
• Forgiving path resolution on obsidian_get_note and obsidian_open_in_ui — silently retries case-mismatched paths against the canonical filename, throws Conflict on ambiguous case matches, and enriches NotFound with Did you mean: …? suggestions when only near-matches exist. obsidian_delete_note is deliberately excluded — a destructive op shouldn't silently rewrite the target path.

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.

{
  "mcpServers": {
    "obsidian": {
      "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):

{
  "mcpServers": {
    "obsidian": {
      "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"
      }
    }
  }
}

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.

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.3.11 or higher (or Node.js v22+).
• The Obsidian Local REST API plugin installed and enabled in your vault. Generate an API key in Settings → Community Plugins → Local REST API and copy it into OBSIDIAN_API_KEY.
• 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).

Installation

1. Clone the repository:

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

2. Navigate into the directory:

   cd obsidian-mcp-server
   

3. Install dependencies:

   bun install
   

4. Configure environment:

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

Configuration

Variable	Description	Default
OBSIDIAN_API_KEY	Required. Bearer token for the Obsidian Local REST API plugin.	—
OBSIDIAN_BASE_URL	Base URL of the Local REST API plugin. Use https://127.0.0.1:27124 for the always-on HTTPS port (self-signed cert).	http://127.0.0.1:27123
OBSIDIAN_VERIFY_SSL	Verify the TLS certificate. Default false because the plugin uses a self-signed cert. On Node, the dispatcher's rejectUnauthorized option handles this without any process-wide change. On Bun, the runtime ignores that option, so the service additionally sets NODE_TLS_REJECT_UNAUTHORIZED=0 — that fallback is scoped to Bun only.	false
OBSIDIAN_REQUEST_TIMEOUT_MS	Per-request timeout in milliseconds.	30000
OBSIDIAN_ENABLE_COMMANDS	Opt-in flag for the command-palette pair (obsidian_list_commands + obsidian_execute_command). Off by default — Obsidian commands are opaque and can be destructive.	false
OBSIDIAN_READ_PATHS	Comma-separated vault-relative folder allowlist for read operations. Prefix-based with implicit recursion; case-insensitive; trailing slashes normalized. Unset = full vault. Write paths are implicitly readable.	unset
OBSIDIAN_WRITE_PATHS	Comma-separated vault-relative folder allowlist for write operations. Same syntax as OBSIDIAN_READ_PATHS. Unset = full vault.	unset
OBSIDIAN_READ_ONLY	Global kill switch. When true, denies every write regardless of OBSIDIAN_WRITE_PATHS, and suppresses the OBSIDIAN_ENABLE_COMMANDS pair (commands can mutate).	false
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_HOST	Host for the HTTP server.	127.0.0.1
MCP_HTTP_PORT	Port for the HTTP server.	3010
MCP_HTTP_ENDPOINT_PATH	Endpoint path for the JSON-RPC handler.	/mcp
MCP_PUBLIC_URL	Public origin override for TLS-terminating reverse-proxy deployments (landing page, Server Card, RFC 9728 metadata).	unset
MCP_AUTH_MODE	Auth mode: none, jwt, or oauth.	none
MCP_AUTH_SECRET_KEY	Required when MCP_AUTH_MODE=jwt. ≥32-char shared secret used to verify incoming JWTs.	—
MCP_LOG_LEVEL	Log level (RFC 5424).	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs
OTEL_ENABLED	Enable OpenTelemetry.	false

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

Running the server

Local development

• Build and run the production version:

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

• Run checks and tests:

  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

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, stateless session mode, and logs to /var/log/obsidian-mcp-server. 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

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and inits the Obsidian service.
src/config	Server-specific environment variable parsing (OBSIDIAN_*) with Zod.
src/services/obsidian	Local REST API client, frontmatter operations, section extractor, domain types.
src/mcp-server/tools	Tool definitions (*.tool.ts) and shared input schemas.
src/mcp-server/resources	Resource definitions (*.resource.ts).
src/mcp-server/prompts	Prompt definitions (currently empty — CRUD/search shape doesn't benefit from a structured template).
tests/	Vitest tests mirroring src/.
docs/	Upstream OpenAPI spec for the Local REST API plugin and the generated tree.md.
changelog/	Per-version release notes; CHANGELOG.md is the regenerated rollup.

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

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.