kObsidian MCP

Filesystem-first MCP server for Obsidian vaults — with an LLM-Wiki layer on top.

Inspired by Andrej Karpathy's LLM Wiki idea. You curate the sources; the LLM does the bookkeeping.

Install · Quick start · Architecture · LLM Wiki · Tools · Docs

Docs: 简体中文 / 日本語 / 한국어

---

🧰 The only Obsidian MCP with workspaces. vault.list / vault.select let an LLM discover and switch between your Obsidian vaults in-session — no restart, no config edit, no per-tool path threading. Backwards compatible with OBSIDIAN_VAULT_PATH. Added in v0.3.0. See docs/WORKSPACES.md.

---

New in v0.3.7

Configure each vault independently with .kobsidian.json: customize wiki folders, filenames, headings, and the stale-page threshold without sharing one configuration across every vault. notes.edit heading inserts also preserve paragraph spacing and join existing lists cleanly.

Configuration example and upgrade notes.

Why kObsidian

• Filesystem-first. Operates on your vault directly. Obsidian doesn't need to be running for 55+ of the 66 tools.
• 66 typed MCP tools across vaults, notes, links, tags, tasks, Dataview, Canvas, Kanban, fenced blocks, Marp, Templates — every one Zod-validated with structuredContent output and the full 4-hint MCP annotation set (readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
• Multi-vault vault.* (v0.3.0). The LLM can vault.list your known Obsidian vaults (discovered from Obsidian's own registry or OBSIDIAN_VAULT_<NAME> env vars) and vault.select between them for the session. Fully backwards compatible: OBSIDIAN_VAULT_PATH stays the default and per-call vaultPath arguments always win.
• LLM-Wiki orchestration — a wiki.* namespace that turns your vault into a compounding knowledge base: ingest sources, auto-update an index + greppable log, lint for orphans / broken links / stale pages. Agent applies cross-refs via a proposedEdits contract so every write is visible in the transcript.
• Both transports. Classic stdio for local MCP clients and Streamable HTTP (Hono) for remote, with CORS preflight, MCP-Protocol-Version handling, origin 403, and optional bearer auth — all per the 2025-11-25 spec.
• Claude Code schema compatibility (v0.3.5+, refined in v0.3.6). Tools advertise JSON Schema 2020-12 over both stdio and stateless Streamable HTTP. Union-shaped tools expose their fields and selectors to the client, while Zod still validates each call and structured output. See compatibility details.
• Ships everywhere. npm (npx -y kobsidian-mcp), cross-platform .mcpb bundles for Claude Desktop drag-and-drop, a smithery.yaml for Smithery, and a server.json for the MCP Registry. Each .mcpb release asset is VirusTotal-scanned with links appended to the release body.

---

Install

Pick your client below. Every client supports the full hybrid mode — filesystem-first tools (80+ of them) run against the vault path alone, and the same config can simultaneously carry the Local REST API key to unlock workspace.*, commands.*, and live DQL via dataview.query*. Set the whole env block once per client and every tool namespace lights up; leave the REST key blank and the filesystem-first tools keep working.

Env var	Needed for
OBSIDIAN_VAULT_PATH	Required everywhere. Absolute path to the vault.
OBSIDIAN_API_URL	Base URL of the Local REST API plugin. Default https://127.0.0.1:27124.
OBSIDIAN_API_VERIFY_TLS	Optional. Defaults to false (the REST API plugin uses a self-signed cert on 127.0.0.1). Set true only after trusting the cert in your OS keychain.
OBSIDIAN_REST_API_KEY	Local REST API plugin bearer key — only for workspace.* / commands.* / live dataview.query*.

Full list in docs/ENVIRONMENT.md. Swap npx for bunx anywhere if you want ≈10 ms cold-start instead of ≈200 ms.

claude mcp add kobsidian -s user \
  --env OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
  --env OBSIDIAN_API_URL=https://127.0.0.1:27124 \
  --env OBSIDIAN_REST_API_KEY=only-if-you-use-workspace-or-commands-tools \
  -- npx -y kobsidian-mcp

On Windows, wrap the command in cmd /c: -- cmd /c npx -y kobsidian-mcp.

Download kobsidian-<platform>.mcpb from the latest release and drag it into Claude Desktop. The installer prompts for vault path + optional API URL / key. Every release asset is VirusTotal-scanned — the links are in the release body.

Build one locally:

bun install
bun run build:compile   # → dist/kobsidian (or .exe on Windows)
bun run bundle:mcpb     # → kobsidian.mcpb

codex mcp add kobsidian \
  --env OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
  --env OBSIDIAN_API_URL=https://127.0.0.1:27124 \
  --env OBSIDIAN_REST_API_KEY=only-if-you-use-workspace-or-commands-tools \
  -- npx -y kobsidian-mcp

Edit ~/.cursor/mcp.json (or the per-project .cursor/mcp.json):

{
  "mcpServers": {
    "kobsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kobsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/vault",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_REST_API_KEY": "only-if-you-use-workspace-or-commands-tools"
      }
    }
  }
}

Or hand a one-click deeplink to your users: cursor://anysphere.cursor-deeplink/mcp/install?name=kobsidian&config=<base64-encoded-config>.

code --add-mcp '{"name":"kobsidian","command":"npx","args":["-y","kobsidian-mcp"],"env":{"OBSIDIAN_VAULT_PATH":"/absolute/path/to/vault","OBSIDIAN_API_URL":"https://127.0.0.1:27124","OBSIDIAN_REST_API_KEY":"only-if-you-use-workspace-or-commands-tools"}}'

Or create .vscode/mcp.json in your workspace with the same shape under a top-level servers key.

gemini mcp add kobsidian \
  --env OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
  --env OBSIDIAN_API_URL=https://127.0.0.1:27124 \
  --env OBSIDIAN_REST_API_KEY=only-if-you-use-workspace-or-commands-tools \
  -- npx -y kobsidian-mcp

Or hand-edit ~/.gemini/settings.json under mcpServers.

Edit ~/.gemini/antigravity/mcp_config.json (Windows: %USERPROFILE%\.gemini\antigravity\mcp_config.json):

{
  "mcpServers": {
    "kobsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kobsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/vault",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_REST_API_KEY": "only-if-you-use-workspace-or-commands-tools"
      }
    }
  }
}

In ~/.config/zed/settings.json:

{
  "context_servers": {
    "kobsidian": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "kobsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/vault",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_REST_API_KEY": "only-if-you-use-workspace-or-commands-tools"
      }
    }
  }
}

{
  "mcp": {
    "kobsidian": {
      "type": "local",
      "command": ["npx", "-y", "kobsidian-mcp"],
      "environment": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/vault",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_REST_API_KEY": "only-if-you-use-workspace-or-commands-tools"
      }
    }
  }
}

droid mcp add kobsidian "npx -y kobsidian-mcp" \
  --env OBSIDIAN_VAULT_PATH=/absolute/path/to/vault \
  --env OBSIDIAN_API_URL=https://127.0.0.1:27124 \
  --env OBSIDIAN_REST_API_KEY=only-if-you-use-workspace-or-commands-tools

Any MCP client that reads a standard mcpServers object will accept:

{
  "mcpServers": {
    "kobsidian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kobsidian-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/vault",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_REST_API_KEY": "only-if-you-use-workspace-or-commands-tools"
      }
    }
  }
}

"type": "stdio" is optional on clients that infer transport from command (Claude Code), but required by Claude Desktop, Cursor, VSCode, and Antigravity — include it for maximum portability.

Smithery

smithery.ai renders an install UI straight from smithery.yaml and collects the four env vars for you — vault path plus the optional Local REST API URL / TLS / bearer key trio, so hybrid mode works out of the box.

From source (contributing / hacking)

git clone https://github.com/bezata/kObsidian
cd kObsidian
bun install
bun run dev:stdio    # or dev:http

---

Obsidian plugins

kObsidian is filesystem-first — 55+ of the 66 tools work against a bare vault directory with no Obsidian plugins installed. The plugins below only matter if you want the specific tool namespaces that depend on them.

Enabling community plugins (one-time, if not already on)

Obsidian ships with community plugins disabled by default. Enable them once per vault:

1. Open your vault in Obsidian.
2. Settings (⚙️, bottom-left) → Community plugins.
3. Click Turn on community plugins.
4. Browse → search → Install → Enable.

Required for the REST-bridged tools

Obsidian Local REST API (by Adam Coddington) — needed for:

• workspace.* (activeFile, openFile, navigate, closeActiveFile, toggleEditMode)
• commands.* (execute, list)
• dataview.query / dataview.listByTag / dataview.listByFolder / dataview.table (runtime DQL — the offline dataview.fields.* / dataview.index / blocks.* tools work without it)
• templates.use with engine: "templater"

Setup after install:

1. Enable the plugin.
2. Open its settings — scroll to API key → click Copy (or Reset first if you want a fresh one).
3. Paste that key as OBSIDIAN_REST_API_KEY in your MCP client config's env: block. The OBSIDIAN_API_URL default (https://127.0.0.1:27124) works out of the box.

Leave the plugin running while you use the REST-bridged tools — the endpoint is local-only (127.0.0.1) so nothing leaves your machine.

Enhances (but not required for) specific tool namespaces

Plugin	Link	What it unlocks
Dataview	id=dataview	All dataview.* tools still work on the raw markdown; Dataview plugin is what makes DQL queries in dataview.query* actually execute. Also renders your fields + queries visually inside Obsidian.
Templater	id=templater-obsidian	Runtime template rendering via the REST API (templates.use with engine:"templater"). The offline filesystem engine (templates.use with engine:"filesystem") and templates.list work without it.
Marp	id=marp-slides	Marp marp.* tools parse + edit Marp-front-matter markdown even without the plugin; the plugin is what renders slides / exports to PDF inside Obsidian.
Kanban	id=obsidian-kanban	kanban.* tools read/write the plain markdown board format regardless of plugin; the plugin is what renders the board as draggable columns inside Obsidian.
Tasks	id=obsidian-tasks-plugin	tasks.* tools understand the Tasks-plugin emoji syntax (📅 ⏳ 🛫 ✅ 🔼 🔁) regardless of plugin; the plugin is what provides filtering / querying / toggling inside Obsidian.

The obsidian://show-plugin?id=… links jump straight to the plugin in Obsidian's in-app browser — click one with Obsidian open and it deep-links to the install screen.

TLDR

You want to …	Minimum you need
Use notes.* / tags.* / links.* / stats.vault / tasks.* / wiki.* / kanban.* / blocks.* / marp.* / canvas.* / templates.list + templates.use (engine:"filesystem") / offline dataview.*	Just a vault path. No plugins required.
Use workspace.* / commands.*	+ Local REST API plugin + API key env var
Run live DQL queries (dataview.query / dataview.listBy* / dataview.table)	+ Local REST API + Dataview
Run Templater templates at runtime	+ Local REST API + Templater

No combination of plugins makes kObsidian depend on Obsidian being running — the REST-bridged tools just return a clear error if the plugin isn't reachable, and the filesystem-first tools keep working.

---

Quick start

Before the first session — kObsidian works on a bare Obsidian vault, but enabling a few Obsidian plugins unlocks the full tool surface. See Obsidian plugins below for the 5-minute setup (Local REST API, Dataview, Templater, Marp, Kanban, Tasks). Skip it if you only need the 80+ filesystem-first tools.

Once installed, a typical session opens with three natural-language prompts. The wiki.* tools + the .claude skills handle the rest.

You:  "Set up a wiki in this vault."
LLM:  wiki.init  →  wiki/{Sources,Concepts,Entities}/ + index.md + log.md + wiki-schema.md

You:  "Ingest this: https://… (paper on Memex)"
LLM:  wiki.ingest  →  creates wiki/Sources/as-we-may-think.md + log entry
      returns proposedEdits:
        - insertAfterHeading  index.md#Sources
        - createStub          Concepts/memex.md
        - createStub          Entities/vannevar-bush.md
      LLM applies each via notes.*  (you see every write in the transcript)

You:  "What does the wiki say about memex vs hypertext?"
LLM:  wiki.query memex  →  top-ranked pages
      notes.read on each  →  cited synthesis
      offers to file the synthesis back via wiki.summaryMerge

You:  "Audit the wiki."
LLM:  wiki.lint  →  {orphans, brokenLinks, stale, missingPages, tagSingletons, indexMismatch}
      proposes concrete fixes; applies after you confirm

Full loop, frontmatter contracts, and the proposedEdits design in docs/wiki.md.

---

Example use cases

The same primitives cover several real-world flavors of knowledge base. Three worked examples below; longer walkthroughs in docs/examples.md.

A. Personal research wiki

You: "Ingest this paper on in-context learning: <url or pasted markdown>"
LLM:  wiki.ingest title="In-Context Learning — A Survey" sourceType=paper
        tags=[icl, prompting] relatedConcepts=[In-Context Learning, Few-Shot Prompting]
        relatedEntities=[Brown 2020]
      → wiki/Sources/in-context-learning-a-survey.md
      → proposedEdits:
          • createStub  wiki/Concepts/in-context-learning.md
          • createStub  wiki/Concepts/few-shot-prompting.md
          • createStub  wiki/Entities/brown-2020.md
          • insertAfterHeading  wiki/index.md#Sources
      LLM applies each via notes.create / notes.edit (mode: "after-heading").

B. Architecture Decision Records (ADRs) for a codebase

Model each ADR as a Source, architectural patterns as Concepts, and services / teams / libraries as Entities. The wiki becomes your ADR archive with cross-links you never have to maintain by hand.

You: "Record ADR-004: we're switching internal service comms from REST
      to gRPC. Context: <paste>"
LLM:  wiki.ingest title="ADR-004 — gRPC for internal service comms"
        sourceType=note tags=[adr, architecture, rpc]
        relatedConcepts=[gRPC, Service Mesh, Internal RPC]
        relatedEntities=[order-service, payment-service, inventory-service]
      → wiki/Sources/adr-004-grpc-for-internal-service-comms.md
      → proposedEdits:
          • createStub   wiki/Concepts/grpc.md
          • createStub   wiki/Concepts/service-mesh.md
          • insertAfterHeading  wiki/Entities/order-service.md#Notable Facts
          • insertAfterHeading  wiki/Entities/payment-service.md#Notable Facts
          • …

Three weeks later —
You: "Why did we pick gRPC for internal comms?"
LLM:  wiki.query "grpc internal comms"
      notes.read top matches
      → "Per [[wiki/Sources/adr-004-grpc-for-internal-service-comms.md|ADR-004]],
         chosen over REST because of native streaming + typed schemas; tradeoff
         accepted: browser clients still use REST via an edge gateway
         ([[wiki/Concepts/service-mesh.md]])."

C. Codebase wiki (design docs + post-mortems + RFCs)

Engineering teams abandon wikis because nobody updates them. Let the LLM do it. Ingest design docs, RFCs, and post-mortems as Sources; architectural patterns become Concepts; services and teams become Entities.

You: "We had an incident today — payment-service timeouts cascaded
      into order-service. Here's the post-mortem: <paste>"
LLM:  wiki.ingest title="Postmortem 2026-04-10 — Payment timeouts cascade"
        sourceType=other tags=[postmortem, incident, reliability]
        relatedConcepts=[Circuit Breaker, Cascade Failure, Timeout Budget]
        relatedEntities=[payment-service, order-service]
      → wiki/Sources/postmortem-2026-04-10-payment-timeouts-cascade.md
      → proposedEdits:
          • createStub  wiki/Concepts/circuit-breaker.md
          • createStub  wiki/Concepts/cascade-failure.md
          • insertAfterHeading  wiki/Entities/payment-service.md#Notable Facts
          • insertAfterHeading  wiki/Entities/order-service.md#Notable Facts

Periodic housekeeping —
You: "Audit the codebase wiki."
LLM:  wiki.lint
      → 3 orphan RFCs (unlinked from any Concept; link or archive?)
      → 1 broken link: [[wiki/Entities/legacy-auth-service.md]]
        (deprecated in Q1; remove the link from
         [[wiki/Sources/adr-002-session-migration.md]]?)
      → 4 post-mortems past the 180-day stale threshold — tag with
        "needs-review" or re-ingest with updated lessons-learned?
      → 2 tag singletons: `retry-logic` (merge into `retry-policy`?),
        `observability` (first use; keep).

Why this works for engineering teams

• The proposedEdits contract means every cross-reference write is visible in the transcript — no silent vault corruption from an LLM hallucination about which services a decision affects.
• The greppable log format (## [YYYY-MM-DD] ingest | ADR-004 …) makes grep '^## \[' wiki/log.md | tail -20 a valid "what did the team decide recently" query.
• wiki.lint surfaces broken links to services that were deprecated months ago — the bookkeeping humans never get around to.

---

Architecture