cyanheads/obsidian-mcp-server

obsidian‑mcp‑server – A Machine‑Context‑Protocol (MCP) bridge to an Obsidian vault

What it is – A TypeScript/Node server that wraps the Obsidian Local REST API and exposes a catalog of MCP‑compatible tools and resources. An LLM‑orchestrator (Claude, Cursor, VS Code, etc.) can call these tools over STDIO or a streamable HTTP endpoint to read, search, and edit notes, tags, and front‑matter inside a local Obsidian vault.

---

Core capabilities (as defined in the README)

Category	Tools / Resources	What you can do
Reading	obsidian_get_note, obsidian_list_notes, obsidian_list_tags, obsidian_list_commands, obsidian://vault/{+path}	Fetch a note as raw markdown, full structured data, a document map, or a single section; list files recursively; enumerate tags with counts; discover command‑palette entries (opt‑in).
Searching	obsidian_search_notes	Text substring search, JSONLogic‑based field queries, or BM25‑ranked Omnisearch (when the Omnisearch plugin is reachable). Results are paginated with opaque cursors.
Writing / Editing	obsidian_write_note, obsidian_append_to_note, obsidian_patch_note, obsidian_replace_in_note, obsidian_manage_frontmatter, obsidian_manage_tags	Create new notes, append content, surgically patch a heading/block/front‑matter, run regex‑based replace, atomically get/set/delete a front‑matter key, add/remove/list tags (front‑matter or inline).
Destructive actions	obsidian_delete_note	Deletes a note, but requires a round‑trip user confirmation before the actual DELETE is performed.
Command‑palette bridge	obsidian_execute_command, obsidian_list_commands	(Optional) List and invoke any Obsidian command‑palette command. Disabled by default; enable with OBSIDIAN_ENABLE_COMMANDS=true.
Resources	obsidian://vault/{+path}, obsidian://tags, obsidian://status	Direct URI‑style access to a note, the full tag index, and server status/auth information.

---

How it works under the hood

1. MCP framework – Built on @cyanheads/mcp-ts-core, which handles tool registration, JSON‑RPC validation, error classification, and the MCP‑specific pagination spec.
2. Stateless proxy – Every tool call forwards to the Obsidian Local REST API plugin running inside the user's Obsidian desktop. No data is stored on the server itself.
3. Transport options – The server can be run as a simple STDIO process (useful for local LLM‑agents) or as a streamable HTTP service (Docker image available on GHCR). Auth can be none, jwt, or oauth.
4. Path‑policy gating – Optional environment variables (OBSIDIAN_READ_PATHS, OBSIDIAN_WRITE_PATHS, OBSIDIAN_READ_ONLY) restrict which vault folders a tool may touch, with clear path_forbidden errors that LLMs can react to.
5. Safety nets – Write tools return previousSizeInBytes / currentSizeInBytes so an agent can detect accidental overwrites. Deletions require explicit confirmation; command‑palette access is opt‑in.

---

Typical use‑cases for AI agents

• RAG (retrieval‑augmented generation) – An LLM can call obsidian_search_notes or obsidian_get_note to pull relevant personal knowledge before answering a user query.
• Dynamic note‑taking – After a conversation, the agent can obsidian_write_note or obsidian_append_to_note to create a daily note, add a summary, or update a project log.
• Tag‑driven organization – obsidian_manage_tags lets an agent keep the tag taxonomy consistent across front‑matter and inline #tag syntax.
• Automated refactoring – Using obsidian_patch_note together with obsidian_get_note's document‑map, an agent can locate a heading and move or replace its content without touching the rest of the file.
• Controlled execution – In a secure deployment, the path‑policy can expose only a scratch/ folder for writes while allowing read‑only access to the whole vault, preventing the model from accidentally modifying important files.

---

Getting started (from the README)

1. Install – npm i -g obsidian-mcp-server or pull the Docker image ghcr.io/cyanheads/obsidian-mcp-server.
2. Run –

   # STDIO mode (default)
   npx obsidian-mcp-server
   
   # HTTP mode (example)
   docker run -p 8080:8080 \
       -e OBSIDIAN_API_KEY=your-key \
       ghcr.io/cyanheads/obsidian-mcp-server
   

   Set OBSIDIAN_API_KEY (or other auth method) to let the server talk to the Obsidian Local REST API.
3. Enable optional features –
   • OBSIDIAN_ENABLE_COMMANDS=true to expose command‑palette tools.
   • OBSIDIAN_READ_ONLY=true for a read‑only deployment.
   • OBSIDIAN_WRITE_PATHS=projects/,scratch/ to limit writes to specific folders.
4. Connect an LLM client – Use the provided MCP install badges for Claude Desktop, Cursor, or VS Code, which automatically add the server as an MCP toolset.

---

Limitations & gotchas (as documented)

• Delete confirmation – obsidian_delete_note cannot be performed by a pure‑stateless client; the client must be able to present the confirmation prompt and resend the answer.
• Omnisearch dependency – BM25 search (mode: "omnisearch") only works if the Obsidian Omnisearch plugin’s HTTP server is reachable at startup; otherwise the mode is omitted.
• Tag listing is vault‑wide – obsidian_list_tags ignores read‑path restrictions, so tag names from outside the allowed read scope can still be returned.
• Section targeting ambiguity – When a heading name matches multiple paths, the server returns ambiguous_section rather than guessing.
• No persistent state – The server does not keep any cache; every call hits the local REST API, so performance depends on the underlying plugin.

---

TL;DR

obsidian-mcp-server is a lightweight, MCP‑compliant bridge that lets AI agents treat an Obsidian vault as a structured knowledge base. It offers 14 fine‑grained tools for reading, searching, and safely editing notes, plus optional command‑palette execution, all behind configurable path‑based permissions and optional authentication.