kObsidian

🧰 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.

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

bun installbun 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

{  "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"      }    }  }}

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"}}'

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

{  "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"      }    }  }}

{  "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

{  "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"      }    }  }}

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/kObsidiancd kObsidianbun installbun 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

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

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

┌──────────────────────────────────────────────────────────────────────┐│                           MCP Clients                                ││   Claude Code · Claude Desktop · Cursor · VSCode · Antigravity · Zed ││   JetBrains AI · Cline · Continue · ChatGPT · Smithery · …           │└────────────────────────────┬─────────────────────────────────────────┘                             │ JSON-RPC 2.0 · MCP 2025-11-25         ┌───────────────────┴──────────────────────┐         ▼                                          ▼┌──────────────────┐                   ┌─────────────────────────┐│ stdio transport  │                   │ Streamable HTTP (Hono)  ││                  │                   │ + OPTIONS / CORS        ││                  │                   │ + MCP-Protocol-Version  ││                  │                   │ + Origin 403 / bearer   │└────────┬─────────┘                   └────────┬────────────────┘         │                                      │         └──────────────────┬───────────────────┘                            ▼          ┌──────────────────────────────────┐          │          McpServer               │          │  ┌────────────┐ ┌─────────────┐  │          │  │  90 Tools  │ │ 4 Resources │  │          │  └────────────┘ └─────────────┘  │          │  ┌────────────┐ ┌─────────────┐  │          │  │ 3 Prompts  │ │ structured  │  │          │  │            │ │   content   │  │          │  └────────────┘ └─────────────┘  │          └────────────┬─────────────────────┘                       │                       ▼          ┌──────────────────────────────────┐          │      Domain layer (pure)         │          │  notes · links · tags · tasks    │          │  dataview · canvas · kanban      │          │  blocks · marp · templates       │          │  wiki/ orchestration             │          └──────┬─────────────────┬─────────┘                 │                 │                 ▼                 ▼         ┌──────────────┐   ┌──────────────────────┐         │  vault/ (FS) │   │ Obsidian Local REST  │         │ authoritative│   │ API plugin (optional)│         └──────────────┘   └──────────────────────┘

Full module map in docs/architecture.md.

LLM Wiki (60 seconds)

The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping. Humans abandon wikis because the maintenance burden grows faster than the value. LLMs don't get bored.

kObsidian implements the LLM Wiki pattern from Andrej Karpathy's gist: a persistent, compounding knowledge base the LLM maintains. The vault becomes a private, curated Memex (Vannevar Bush, 1945) where cross-references, log-keeping, and lint are the LLM's job while you focus on curating sources and asking questions.

"Instead of just retrieving from raw documents at query time, the LLM incrementally builds and maintains a persistent wiki — a structured, interlinked collection of markdown files that sits between you and the raw sources." — Andrej Karpathy

              User drops a source                      │                      ▼            ┌──────────────────────┐    proposedEdits            │     wiki.ingest      │ ─────────────────────┐            └──────────┬───────────┘                      │                       │ creates 1 file                   ▼                       │              ┌──────────────────────────────┐                       ▼              │ LLM applies edits via        │              wiki/Sources/           │  notes.edit (after-heading)  │              <slug>.md               │  notes.edit (replace)        │                       │              │  notes.create                │                       │ appends      └──────────────────────────────┘                       ▼                 wiki/log.md
   Anytime: wiki.query   → top pages → notes.read → cited synthesis   Periodic: wiki.lint   → orphans · broken · stale · missing · tag-drift   Curate:   wiki.summaryMerge — add cited section to concept/entity page

Default layout under the vault:

wiki/├── Sources/           per-source summary pages├── Concepts/          topic / idea pages (LLM-maintained)├── Entities/          people / places / orgs / works├── index.md           categorized catalog (wiki.indexRebuild)├── log.md             greppable chronological log└── wiki-schema.md     vault-local copy of the contract

The key design decision is that wiki.ingest never rewrites cross-references blindly. It creates exactly one file (the Sources page), appends one file (log.md), and returns a proposedEdits array the agent applies with existing notes.* tools. Every write is visible in the transcript — so LLM hallucinations show up as reviewable edits rather than silent vault corruption.

Full contract in docs/wiki.md.

Claude Code skills

Four skills at skills/ trigger on natural language: wiki-bootstrap, wiki-ingest, wiki-query, wiki-lint. Copy or symlink them into ~/.claude/skills/ — see skills/README.md.

Tool surface

66 MCP tools across 16 namespaces (v0.2.5 consolidated from ~90 to 62; v0.3.0 added the vault.* namespace for multi-vault support — see CHANGELOG for the full history). Always-current inventory at docs/tool-inventory.json.

Client-safety annotations (MCP 2025-11-25):

MCP resources (URI-addressable; any client can browse without tool calls):

kobsidian://wiki/index              wiki/index.mdkobsidian://wiki/log                wiki/log.mdkobsidian://wiki/schema             wiki/wiki-schema.mdkobsidian://wiki/page/{+path}       any Sources/Concepts/Entities page

MCP prompts (for clients that don't consume the skills/ files): ingest-source, answer-from-wiki, health-check-wiki.

Details in docs/tools.md.

Configuration

Every wiki tool also accepts a per-call wikiRoot override, and wiki.ingest accepts per-call indexHeading / conceptHeading / entityHeading overrides for vaults whose pages use localized headings (e.g. ## Fontes). When a target heading is missing from a page, the proposal degrades to append so it can still be applied via notes.edit.

Per-vault config file

Settings that belong to one vault rather than to the server — folder names, filenames, and section headings of a localized wiki — go in a .kobsidian.json at the vault root. Every key is optional and beats the matching env var; a per-call tool argument beats both (per-call → .kobsidian.json → env → default).

{  "$schema": "https://raw.githubusercontent.com/bezata/kObsidian/main/docs/kobsidian.config.schema.json",  "wiki": {    "root": "wiki",    "sourcesDir": "Fontes",    "staleDays": 90,    "headings": {      "indexSources": "Fontes",      "indexConcepts": "Conceitos",      "indexEntities": "Entidades",      "conceptPage": "Discussão",      "entityPage": "Fatos Notáveis"    }  }}

Unknown keys and malformed JSON are rejected with the file path in the error so typos surface immediately; vault.current returns the effective configuration under config (or the error).

Docs

Localized docs are available in 简体中文, 日本語, and 한국어.

Roadmap

The next two milestones are tracked in TODO.md:

• v0.4 — Obsidian LiveSync bridge. Free, end-to-end-encrypted vault access via the community Self-Hosted LiveSync plugin (CouchDB / S3 / R2 / WebRTC peer) — so an MCP client can reach the same Obsidian vault from any machine the user owns, without Obsidian itself being live.
• v0.5 — Cross-semantic vault verification. A wiki.crossCheck tool that reconciles two or more LiveSync-paired vaults at the wiki layer, gated by a new schema_version frontmatter field that uses the project's semver discipline as the compatibility contract.

TODO.md carries the motivation, the per-milestone task breakdown, and the rules for how items move from there into the CHANGELOG.

Development

bun installbun run typecheckbun run lintbun run test          # 56 tests across 14 filesbun run build         # node-target stdio.js + bun-target http.jsbun run inventory     # regenerate docs/tool-inventory.json

Project conventions in AGENTS.md.

Security & supply chain

• Every .mcpb release asset is VirusTotal-scanned. The Release workflow uploads each kobsidian-<platform>.mcpb bundle to VirusTotal via crazy-max/ghaction-virustotal@v4 right after the release is published, then appends the analysis links to the release body. Any user installing from a GitHub release can click through to the public VirusTotal report for their platform's bundle before they run it — no trust in the maintainer required.

• Transport hardening. Streamable HTTP validates Origin against an allowlist (403 on mismatch), implements CORS preflight (OPTIONS /mcp → 204 + Access-Control-*), requires or defaults MCP-Protocol-Version, and supports optional bearer auth via KOBSIDIAN_HTTP_BEARER_TOKEN. stdio has no network surface.

• Pinned SDK floor. @modelcontextprotocol/sdk@^1.26.0 — mitigates GHSA-345p-7cg4-v4c7 (cross-client response leak) and CVE-2026-0621 (UriTemplate ReDoS). This repo pins 1.30.0.

• npm Trusted Publishing. No long-lived NPM_TOKEN is stored in the repo. GitHub Actions mints a short-lived OIDC token on every tag push and the npm CLI exchanges it for a one-time publish token scoped to this exact workflow file (.github/workflows/release.yml on the bezata/kObsidian repo). Provenance attestations are automatic — every published version has a cryptographically-linked build statement pointing at the exact Actions run that produced it. Forks, other branches, or modified workflow files cannot publish — the OIDC audience claim won't match.

Full notes in docs/SECURITY.md.

Compatibility notes

• Protocol version — 2025-11-25 (current MCP spec). HTTP clients without MCP-Protocol-Version fall back to 2025-03-26 per spec; explicit-but-unsupported versions return 400.
• Dataview split — offline tools index frontmatter / inline / list / task / fenced dataview / fenced dataviewjs blocks. Runtime DQL is delegated to Obsidian + Dataview through the Local REST API. DataviewJS is source-preserving but not executed inside this server.
• Mermaid + Marp — source-preserving parse/edit only; rendering is the client's job.
• SDK floor — @modelcontextprotocol/sdk@^1.26.0 (mitigates GHSA-345p-7cg4-v4c7 cross-client response leak + CVE-2026-0621 UriTemplate ReDoS). This repo pins 1.30.0.

Credits

• LLM Wiki pattern — Andrej Karpathy's gist. kObsidian is one concrete, filesystem-first TypeScript implementation of the idea.
• Memex — Vannevar Bush, As We May Think, 1945. The associative-trails concept is what the wiki's cross-reference graph tries to be.
• Model Context Protocol — Anthropic + the Agentic AI Foundation.
• Obsidian — obsidian.md. The vault format is authoritative; kObsidian respects it, doesn't migrate it.

License

MIT — see LICENSE. Contributions welcome; open an issue first for anything non-trivial.