Skip to main content
Glama
kObsidian MCP

kObsidian MCP

by bezata

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.

npm version npm downloads GitHub release license Release CI

MCP Bun TypeScript Tools Resources Prompts Smithery MCP Registry VirusTotal

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

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

kObsidian MCP server


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

Related MCP server: obsidian-mcp

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

┌──────────────────────────────────────────────────────────────────────┐
│                           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.

Namespace

Count

Highlights

vault.*

4

list · current · select · reset — multi-vault discovery and session switching (v0.3.0)

notes.*

8

read (content/metadata/stats via include) · create (note or folder) · edit (replace/append/prepend/after-heading/after-block) · frontmatter · delete · move · list · search

tags.*

4

modify (add/remove/replace/merge) · search · analyze · list

links.*

8

Backlinks · outgoing · broken · orphans · hubs · graph · health · connections

stats.*

1

stats.vault (per-note stats moved into notes.read)

tasks.*

5

Tasks-plugin format (📅 ⏳ 🛫 ✅ 🔼 🔁) — search · create · toggle · updateMetadata · stats

dataview.*

7

query + sugar wrappers (listByTag/listByFolder/table) · index · fields.read · fields.write

blocks.*

3

Unified fenced-block API (list/read/update) across dataview, dataviewjs, mermaid

marp.*

2

read (deck/slides/slide) · update (slide/frontmatter)

kanban.*

3

parse · stats · card (add/move/toggle)

canvas.*

4

create · parse · connections · edit (add-node/add-edge/remove-node)

templates.*

2

list · use (engine × action)

workspace.*

5

Live Obsidian UI bridge (requires Local REST API plugin)

commands.*

2

list (with optional query) · execute

wiki.*

7

init · ingest · log · indexRebuild · query · lint · summaryMerge

system.*

1

version

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

Hint

Tools

readOnlyHint: true (clients can auto-approve)

47

destructiveHint: true (clients prompt more firmly)

6

idempotentHint: true (safe to retry)

12

openWorldHint: true (reaches outside the vault)

16

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

kobsidian://wiki/index              wiki/index.md
kobsidian://wiki/log                wiki/log.md
kobsidian://wiki/schema             wiki/wiki-schema.md
kobsidian://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

Env var

Default

Purpose

OBSIDIAN_VAULT_PATH

—

Required. Absolute path to the vault.

OBSIDIAN_API_URL

https://127.0.0.1:27124

Obsidian Local REST API base; only for workspace.* / commands.* / dataview.query*.

OBSIDIAN_API_VERIFY_TLS

false

Set true if you've trusted the REST API's self-signed cert.

OBSIDIAN_REST_API_KEY

—

Bearer key for the REST API plugin (if used).

KOBSIDIAN_HTTP_HOST

127.0.0.1

Bind host for dev:http.

KOBSIDIAN_HTTP_PORT

3000

Bind port for dev:http.

KOBSIDIAN_HTTP_BEARER_TOKEN

—

Optional bearer for the Streamable HTTP transport.

KOBSIDIAN_ALLOWED_ORIGINS

http://localhost,http://127.0.0.1

Comma-separated CORS allowlist.

KOBSIDIAN_WIKI_ROOT

wiki

Wiki directory under the vault.

KOBSIDIAN_WIKI_SOURCES_DIR

Sources

Per-source summary pages.

KOBSIDIAN_WIKI_CONCEPTS_DIR

Concepts

Topic / idea pages.

KOBSIDIAN_WIKI_ENTITIES_DIR

Entities

People / places / orgs / works.

KOBSIDIAN_WIKI_INDEX_FILE

index.md

Wiki catalog filename.

KOBSIDIAN_WIKI_LOG_FILE

log.md

Wiki log filename.

KOBSIDIAN_WIKI_SCHEMA_FILE

wiki-schema.md

Seed schema filename.

KOBSIDIAN_WIKI_STALE_DAYS

180

wiki.lint stale-page threshold.

KOBSIDIAN_WIKI_INDEX_SOURCES_HEADING

Sources

index.md section that lists sources; wiki.ingest files new entries under it.

KOBSIDIAN_WIKI_INDEX_CONCEPTS_HEADING

Concepts

index.md section that lists concepts.

KOBSIDIAN_WIKI_INDEX_ENTITIES_HEADING

Entities

index.md section that lists entities.

KOBSIDIAN_WIKI_CONCEPT_PAGE_HEADING

Discussion

Concept-page heading that receives wiki.ingest citations / wiki.summaryMerge sections.

KOBSIDIAN_WIKI_ENTITY_PAGE_HEADING

Notable Facts

Entity-page heading that receives wiki.ingest citations / wiki.summaryMerge sections.

KOBSIDIAN_VAULT_CONFIG_FILE

.kobsidian.json

Vault-relative path of the per-vault config file (below).

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 한국어.

architecture.md

Stack, module map, layering rules

wiki.md

LLM-Wiki contract, loop, frontmatter, lint categories

examples.md

Personal research wiki · engineering ADRs · codebase wiki — end-to-end

tools.md

Namespace table, annotations, resources, prompts

SECURITY.md

Origin/CORS, VirusTotal scans, env hygiene

TESTING.md

bun run … commands + coverage

ENVIRONMENT.md

Every env var with defaults

MIGRATION.md

Upgrade notes


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 install
bun run typecheck
bun run lint
bun run test          # 56 tests across 14 files
bun run build         # node-target stdio.js + bun-target http.js
bun 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

License

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

Available Tools

66 tools
blocks.listList Fenced BlocksA
Read-onlyIdempotent

List fenced code blocks of the supported knowledge-base languages (dataview, dataviewjs, mermaid) in a single note or across the vault. Use this to discover what DQL, DataviewJS, or Mermaid blocks exist before reading or updating them. Omit language to list blocks of all three types in one call. Vault-wide scanning is only supported for Mermaid; for Dataview languages a filePath is required. Returns {total, items} where each item carries at minimum {filePath, language, index, id?}. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath, language, vaultPath. Returns: items, total, filePath

blocks.readRead Fenced BlockA
Read-onlyIdempotent

Read one fenced block's source and language-specific metadata. Locate the block by blockId (preferred, stable) or index (0-based within the language group in the file; defaults to 0). language is required so the tool can dispatch to the correct parser and return the right metadata (Mermaid directives, Dataview DQL parts, etc.). Fails with not_found when no block matches the locator. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), language (required), index, blockId, +1 more. Returns: One block with its full source and any per-language metadata (directives, spans…

blocks.updateUpdate Fenced BlockA
DestructiveIdempotent

Replace one fenced block's body source-preservingly — the surrounding fences, language tag, and neighbouring content are untouched. Locate the block by blockId or index. language acts as a guard: if the located block is not of the declared language, the update fails. source is the replacement body WITHOUT the surrounding ``` fences. Idempotent — re-running with identical inputs is a no-op on the file contents. Destructive — overwrites the previous block body in place.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Replace the first Mermaid diagram in a note:

{
  "filePath": "Diagrams/system-overview.md",
  "language": "mermaid",
  "index": 0,
  "source": "flowchart TD\n  A --> B"
}

Example 2 — Update a DQL query block by stable id:

{
  "filePath": "Dashboards/Inbox.md",
  "language": "dataview",
  "blockId": "inbox-open",
  "source": "TASK\nFROM #inbox\nWHERE !completed"
}

Inputs: source (required), filePath (required), language (required), index, +2 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

canvas.connectionsCanvas Node ConnectionsA
Read-onlyIdempotent

Return the incoming and outgoing edges of a single canvas node. Use this to walk the canvas graph one node at a time without loading the full document. Read-only. For full-graph parsing, use canvas.parse.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: nodeId (required), filePath (required), vaultPath. Returns: nodeId, filePath, incoming, outgoing

canvas.createCreate CanvasA

Create a new empty Obsidian canvas (.canvas) file at the given path. Fails if the path already exists unless overwrite: true is passed. Canvas files are JSON documents that Obsidian renders as an infinite spatial whiteboard of nodes and edges. Use canvas.edit to add nodes/edges once the file exists.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), overwrite, vaultPath. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

canvas.editEdit CanvasA

Mutate a canvas: add a node, add an edge, or remove a node. The op field selects the mutation. add-node needs nodeType (text for inline markdown or file for an embedded note), content, x, y (plus optional width/height). add-edge needs fromNode and toNode ids (plus optional label). remove-node needs nodeId — removing a node also removes every edge incident to it (destructive). Returns a standard mutation envelope.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Add a text node to a canvas:

{
  "op": "add-node",
  "filePath": "Boards/map.canvas",
  "nodeType": "text",
  "content": "Research question",
  "x": 0,
  "y": 0,
  "width": 280,
  "height": 80
}

Example 2 — Connect two existing nodes with a labelled edge:

{
  "op": "add-edge",
  "filePath": "Boards/map.canvas",
  "fromNode": "n1",
  "toNode": "n2",
  "label": "depends on"
}

Example 3 — Remove a node and all its edges:

{
  "op": "remove-node",
  "filePath": "Boards/map.canvas",
  "nodeId": "n3"
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

canvas.parseParse CanvasA
Read-onlyIdempotent

Parse an Obsidian canvas file and return its full structure: every node (text, file, link, group) and every edge. Use this when you need the complete graph; for just the neighbours of a specific node, call canvas.connections instead. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), vaultPath. Returns: edges, nodes, filePath

commands.executeExecute Obsidian CommandA
Destructive

Execute an Obsidian command by its internal id (as returned by commands.list). args is an optional argument map passed to the command (most built-in commands take no arguments). Requires the Local REST API plugin. Destructive — the effect depends entirely on what the command does, so verify the command id before calling.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Inputs: commandId (required), args. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

commands.listList Or Search Obsidian CommandsA
Read-onlyIdempotent

List Obsidian commands. With no query, returns every registered command (both built-in and plugin-provided). With a query string, returns commands whose id or display name matches — substring match, case-insensitive. Read-only. Use this to discover command ids before calling commands.execute. Requires the Local REST API plugin.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Inputs: query. Returns: Standard list envelope used by list/search tools.

dataview.fields.readRead Dataview FieldsA
Read-onlyIdempotent

Read Dataview fields from the vault. op:'extract' returns every field declared in a single note (page, list-item, and task-line fields combined). op:'search' scans the whole vault for notes whose fields match a key (and optionally a value coerced by valueType); use scope to restrict which field kinds are considered. Read-only. For mutating fields, use dataview.fields.write.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Returns: Freeform object. The specific shape depends on the tool; see the tool description.

dataview.fields.writeWrite Dataview FieldsA
Idempotent

Insert or remove a Dataview field in a single note. op:'add' inserts a key:: value field; syntaxType picks the rendering (full-line = own line; bracket = [key:: value]; paren = (key:: value)); insertAt chooses placement (start, end, afterFrontmatter) unless lineNumber is given for precise control. op:'remove' deletes every occurrence of key (optionally restricted to a single lineNumber or a Dataview scope). Idempotent — re-running with the same args converges on the same document state.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Add a full-line priority field after the frontmatter:

{
  "op": "add",
  "filePath": "Projects/Alpha.md",
  "key": "priority",
  "value": "high",
  "syntaxType": "full-line",
  "insertAt": "afterFrontmatter"
}

Example 2 — Remove every occurrence of the status field from a note:

{
  "op": "remove",
  "filePath": "Projects/Alpha.md",
  "key": "status",
  "scope": "all"
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

dataview.indexRead Dataview IndexA
Read-onlyIdempotent

Parse a single note and return everything Dataview would index from it: page-level metadata (title, aliases, tags, frontmatter fields), list-item fields, task-line fields, and both DQL and DataviewJS block locations. Read-only, runs locally (does NOT require the Local REST API). Use this to understand what Dataview sees in a note without running a query.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

dataview.listByFolderList Notes By FolderA
Read-onlyIdempotent

Convenience wrapper that runs LIST FROM "folder" (optionally with WHERE, SORT, and LIMIT clauses). Useful when you want every note under a vault folder. Requires the Dataview and Local REST API plugins.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: folder (required), limit, sortBy, whereClause. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

dataview.listByTagList Notes By TagA
Read-onlyIdempotent

Convenience wrapper that runs LIST FROM #tag (optionally with WHERE, SORT, and LIMIT clauses). Returns the same shape as dataview.query. Requires the Dataview and Local REST API plugins. Use this instead of authoring raw DQL when filtering by a single tag.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: tag (required), limit, sortBy, whereClause. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

dataview.queryRun Dataview QueryA
Read-onlyIdempotent

Execute an arbitrary Dataview Query Language (DQL) query through the Obsidian Local REST API. The query string is raw DQL — e.g. LIST FROM #inbox, TASK WHERE !completed, TABLE file.mtime FROM "Journal". Requires the Dataview plugin to be enabled in Obsidian and the Local REST API plugin to be configured (OBSIDIAN_API_URL/OBSIDIAN_REST_API_KEY). For common patterns (list-by-tag, list-by-folder, table) the sugar tools dataview.listByTag/listByFolder/table are easier to use — prefer those when applicable and fall back to dataview.query for custom DQL.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: query (required). Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

dataview.tableRun Dataview Table QueryA
Read-onlyIdempotent

Convenience wrapper that runs TABLE field1, field2, … FROM … with optional WHERE, SORT, and LIMIT clauses. Use this when you need structured columnar output. Requires the Dataview and Local REST API plugins.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: fields (required), limit, sortBy, fromClause, +1 more. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

kanban.cardModify Kanban CardA

Add, move, or toggle a card on a Kanban board. The op field selects the mutation and determines which other fields are required: add needs columnName and cardText (plus optional status, dueDate, position); move needs cardText, fromColumn, toColumn (plus optional position); toggle needs cardText (plus optional columnName to scope the search). Missing destination columns are created automatically. Returns a {changed, target, summary, ...} mutation envelope.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Add a new card to the Todo column with a due date:

{
  "op": "add",
  "filePath": "Boards/Project.md",
  "columnName": "Todo",
  "cardText": "Write migration doc",
  "dueDate": "2026-05-01",
  "position": "end"
}

Example 2 — Move a card from In Progress to Done:

{
  "op": "move",
  "filePath": "Boards/Project.md",
  "cardText": "Write migration doc",
  "fromColumn": "In Progress",
  "toColumn": "Done"
}

Example 3 — Toggle a card's completion in any column:

{
  "op": "toggle",
  "filePath": "Boards/Project.md",
  "cardText": "Write migration doc"
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

kanban.parseParse Kanban BoardA
Read-onlyIdempotent

Parse a markdown Kanban board file into its column/card structure. Use this when you need the full board content — each column's name and its cards with their completion state. Works with the obsidian-kanban plugin's markdown format. Read-only. For completion counts and ratios instead of the full card list, use kanban.stats.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), vaultPath. Returns: columns, filePath

kanban.statsKanban Board StatisticsA
Read-onlyIdempotent

Summarise a Kanban board: total cards, completed count, incomplete count, completion rate, and per-column breakdown. Use this for dashboards or progress checks where you don't need each card's full text. Read-only. Use kanban.parse when you need the actual card content.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: filePath (required), vaultPath. Returns: total, byColumn, filePath, completed, +2 more

links.brokenFind Broken LinksA
Read-onlyIdempotent

Find every link in the vault (or a directory subtree) whose target does not resolve to an existing note. Each result carries the source file, line number, link text, and unresolved target. Read-only. Pair with notes.move (with updateLinks:true) to fix them after moves.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: directory, vaultPath. Returns: Standard list envelope used by list/search tools.

links.connectionsExplore Note ConnectionsA
Read-onlyIdempotent

Explore the graph neighbourhood around a seed note — direct and multi-hop connections up to depth hops (default 2). Returns the set of reachable notes plus the paths that reach them. Higher depth values blow up result size quickly; keep it ≤3 unless you know the graph is sparse. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: noteName (required), depth, vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

links.graphGet Link GraphA
Read-onlyIdempotent

Build a full vault link graph: every note becomes a node, every outbound link becomes a directed edge. Return shape is {nodes, edges, stats} where nodes carry basic metadata (path, title) and edges carry source/target and link kind. Expensive for large vaults — prefer links.backlinks, links.outgoing, or links.connections for targeted queries. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

links.healthAnalyze Link HealthA
Read-onlyIdempotent

Summarise link health for the whole vault: total link count, broken-link count and ratio, orphan-note count, average outbound/inbound link density, and a list of the top hub notes. Read-only. Use this as a dashboard check; call links.broken/links.orphaned/links.hubs for the full per-item lists.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

links.hubsFind Hub NotesA
Read-onlyIdempotent

Return notes with at least minOutlinks outgoing links (default 10), sorted by outbound count descending — the vault's connective tissue / MOCs / curated indexes. Each result carries {path, title, outbound, inbound}. Read-only. Use this to find pages that already act as navigational anchors (good seeds for links.connections); use links.health for a single rolled-up score across the whole vault, and links.graph when you need the full raw edge list rather than just the dense nodes.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath, minOutlinks. Returns: Standard list envelope used by list/search tools.

links.orphanedFind Orphaned NotesA
Read-onlyIdempotent

Return every note with zero incoming AND zero outgoing links — i.e., notes that are disconnected from the rest of the vault graph. Useful for cleanup passes. Read-only. Often paired with links.hubs and links.broken in a weekly vault-health routine.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath. Returns: Standard list envelope used by list/search tools.

links.outgoingGet Outgoing LinksA
Read-onlyIdempotent

Extract every link FROM a note (outbound references) — wiki-style [[…]] and markdown-style […](…). When checkValidity:true, each entry carries a valid flag indicating whether the target path resolves in the vault. Read-only. For inbound references (what points AT the note), use links.backlinks.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: path (required), vaultPath, checkValidity. Returns: Standard list envelope used by list/search tools.

marp.readRead Marp DeckA
Read-onlyIdempotent

Read some or all of a Marp presentation deck (a markdown file with marp: true frontmatter and --- slide separators). The part field selects what to return: deck returns the whole deck (frontmatter, all slides, directives); slides returns a list of slide summaries (separator and directive metadata, no body); slide returns one slide's full source, located by slideId or 0-based index. Output shape varies by part — see the description of each variant. Read-only. Use marp.update to mutate.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Returns: Freeform object. The specific shape depends on the tool; see the tool description.

marp.updateUpdate Marp DeckA
DestructiveIdempotent

Mutate a Marp deck in place. part:'slide' replaces one slide's body (located by slideId or index) without touching neighbouring slides. part:'frontmatter' merges fields into the deck's frontmatter — unspecified fields are preserved; pass null to a field to unset it. Idempotent — re-running with identical inputs is a no-op on the file contents. Destructive — overwrites in place.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Replace the second slide's body:

{
  "part": "slide",
  "filePath": "Decks/launch.md",
  "index": 1,
  "source": "# New headline\n\nUpdated body"
}

Example 2 — Change the deck's theme and set a new title:

{
  "part": "frontmatter",
  "filePath": "Decks/launch.md",
  "fields": {
    "theme": "gaia",
    "title": "Launch plan"
  }
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

notes.createCreate Note Or FolderA

Create a new note or folder in the vault. kind:'note' creates a markdown note at path with the given content; ifExists controls collision behavior (error = fail, default; replace = overwrite; skip = no-op). kind:'folder' creates a directory at path (intermediate folders are created automatically; idempotent — re-creating an existing folder is a no-op). Returns the standard mutation envelope.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Create a new note, failing if it exists:

{
  "kind": "note",
  "path": "Journal/2026-04-24.md",
  "content": "# Today\n"
}

Example 2 — Ensure a folder exists (idempotent):

{
  "kind": "folder",
  "path": "Projects/Alpha/Reports"
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

notes.deleteDelete NoteA
Destructive

Delete a note from the vault. Destructive — the file is removed from disk. Fails with not_found when the path does not exist. There is no undo; use with care. For folders, call notes.move to an archive location instead (folder deletion is not exposed as a tool to avoid accidental cascading deletes).

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: path (required), vaultPath. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

notes.editEdit NoteA

Mutate the body of an existing note. The mode field selects how content is applied: replace overwrites the whole note; append adds to the end; prepend adds after the frontmatter (or at the top if none); after-heading inserts after the first heading whose text matches anchor (no leading #); after-block inserts after the block reference ^anchor. Fails if the note does not exist — use notes.create first. replace mode is idempotent-destructive; the others are additive.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Append a new journal entry to the end of today's note:

{
  "mode": "append",
  "path": "Journal/2026-04-24.md",
  "content": "\n## Afternoon\n\nFinished the tool consolidation."
}

Example 2 — Insert content after a specific heading:

{
  "mode": "after-heading",
  "path": "Projects/Alpha.md",
  "anchor": "Open questions",
  "content": "- Do we need to bump the Zod major?\n"
}

Example 3 — Insert after a block reference:

{
  "mode": "after-block",
  "path": "Notes/idea.md",
  "anchor": "idea-1",
  "content": "Follow-up thought …"
}

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

notes.frontmatterEdit FrontmatterA
Idempotent

Set or unset fields in a note's YAML frontmatter. set is a map of {field: value} pairs to write; unset is a list of field names to delete. strategy:'merge' (default) leaves unspecified fields untouched; strategy:'replace' overwrites the entire frontmatter block with set (any field not in set is dropped). At least one of set or unset is required. Idempotent — re-running with the same arguments converges on the same frontmatter state.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Set two fields, merging with existing frontmatter:

{
  "path": "Projects/Alpha.md",
  "set": {
    "status": "in-progress",
    "owner": "behzat"
  }
}

Example 2 — Remove a field:

{
  "path": "Projects/Alpha.md",
  "unset": [
    "draft"
  ]
}

Inputs: path (required), set, unset, strategy, +1 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

notes.listList Notes And FoldersA
Read-onlyIdempotent

List notes and/or folders in the vault, optionally scoped to a folder and filtered by creation/modification date. include selects what to return (notes, folders, or both). recursive:true descends into subfolders. since/until (ISO dates) combined with dateField (created or modified, default modified) narrow the result by date. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: since, until, folder, include, +3 more. Returns: Standard list envelope used by list/search tools.

notes.moveMove Note Or FolderA
DestructiveIdempotent

Move a note or folder to a new path. kind:'note' moves a single .md file; kind:'folder' moves a directory and every note beneath it. When updateLinks:true (the default), wiki and markdown links elsewhere in the vault that reference the moved path are rewritten to point at the new location. Destructive — overwrites or replaces existing content at the destination. Fails when the source does not exist.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g. `created`, `appended`, `before`/`after` counts) — those are documented in the tool description.

notes.readRead NoteA
Read-onlyIdempotent

Read a note and return any combination of its body, parsed frontmatter metadata, and lightweight statistics. include selects which sections to return — default is ['content', 'metadata']. Ask for ['stats'] alone when you only need word/character/heading/link/task counts and want to skip loading the full body. Read-only. Fails with not_found when path does not exist.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: path (required), include, vaultPath. Returns: path, stats, content, metadata

notes.searchSearch NotesA
Read-onlyIdempotent

Full-text search across every note in the vault. The query supports plain text and lightweight prefix filters: tag:foo restricts to notes carrying #foo, and path:Journal/ restricts to notes under a folder. contextLength controls how many characters of surrounding context are returned per match (default 80). Read-only. For pure tag or date filtering, tags.search and notes.list are faster.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: query (required), vaultPath, contextLength. Returns: Standard list envelope used by list/search tools.

stats.vaultVault StatisticsA
Read-onlyIdempotent

Return aggregate statistics for the whole vault: total note count, total word count, total character count, total task count (open and completed), tag usage summary, and file size footprint. Read-only, scans every .md file. For per-note statistics use notes.read with include: ['stats'].

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

system.versionServer VersionA
Read-onlyIdempotent

Return the running kObsidian server's package name, semver version, host runtime (bun or node), and runtime version. Use this as a health-check or to confirm which server build a client is talking to. Read-only; zero side effects.

Inputs: no named parameters. Returns: Return shape for `system.version`.

tags.analyzeAnalyze Note TagsA
Read-onlyIdempotent

Return the tags present in a single note, split into frontmatterTags, inlineTags, and their de-duplicated union allTags. Use this when you have one note and want to know what tags it carries — contrast with tags.search, which scans the whole vault for one specific tag. Read-only.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: path (required), vaultPath. Returns: path, allTags, inlineTags, frontmatterTags

tags.listList All TagsA
Read-onlyIdempotent

List every unique tag used across the vault (frontmatter and inline combined). With includeCounts: true, each item includes how many notes carry the tag; sortBy lets you sort by name or count (the latter requires counts). Read-only. For finding notes carrying a specific tag, use tags.search.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: sortBy, vaultPath, includeCounts. Returns: items, total

tags.modifyModify TagsA
Idempotent

Mutate the frontmatter tags list of a single note. Four ops are supported: add unions the incoming tags with the existing list (duplicates dropped); remove drops any incoming tag currently present; replace overwrites the list entirely; merge is an alias for add. Leading # on incoming tags is stripped automatically. This tool only touches the frontmatter block — inline #tag occurrences in the body are left untouched. Idempotent: repeated calls with the same op and tags converge on the same result. Returns {changed, target, summary, op, tagsAfter}.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Add two tags to a note (idempotent):

{
  "path": "Projects/Alpha.md",
  "op": "add",
  "tags": [
    "in-progress",
    "priority/high"
  ]
}

Example 2 — Replace a note's entire tag set:

{
  "path": "Inbox/today.md",
  "op": "replace",
  "tags": [
    "processed"
  ]
}

Inputs: op (required), path (required), tags (required), vaultPath. Returns: op, target, changed, summary, +2 more

tags.searchSearch Notes By TagA
Read-onlyIdempotent

Find every note in the vault that contains a given tag, either in frontmatter tags or as an inline #tag in the body. Leading # on the query is stripped. For each hit, the result carries {file, absolutePath, tagLocations: {frontmatter, inline}} so callers can distinguish where the tag came from. Read-only. For analyzing tags of ONE specific note (not a vault-wide search), use tags.analyze instead.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: tag (required), vaultPath. Returns: tag, items, total

tasks.createCreate TaskA

Append a new task line to a note. The task is written in Tasks-plugin format: - [ ] <content> {metadata emojis}. Optional metadata (priority, dueDate, scheduledDate, startDate, doneDate, createdDate, recurrence) is encoded as the plugin's convention emojis (🔺⏫📅⏳🛫✅➕🔁). Returns the standard mutation envelope with the 1-based lineNumber where the task was inserted.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Append a simple task with a due date:

{
  "filePath": "Tasks.md",
  "content": "Write the v0.3.0 migration doc",
  "dueDate": "2026-05-01"
}

Example 2 — Append a high-priority weekly recurring task:

{
  "filePath": "Tasks.md",
  "content": "Weekly review",
  "priority": "high",
  "recurrence": "every week on Sunday"
}

Inputs: content (required), filePath (required), status, dueDate, +7 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

tasks.searchSearch TasksA
Read-onlyIdempotent

Scan the vault for Tasks-plugin-style markdown task lines (- [ ] / - [x]) and filter by status, priority, due date range, recurrence, or tag. Result items include the task text, source file, line number, status, and parsed metadata — enough to locate and further manipulate each task via tasks.toggle or tasks.updateMetadata. sortBy controls ordering; limit caps the result count. Read-only. For vault-wide counts without per-task detail, use tasks.stats.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: tag, limit, sortBy, status, +6 more. Returns: Standard list envelope used by list/search tools.

tasks.statsTask StatisticsA
Read-onlyIdempotent

Return aggregate task statistics for the whole vault: total tasks, incomplete count, completed count, overdue count (due date passed and still incomplete), upcoming counts by horizon (today/this-week/next-week), and per-priority breakdown. Read-only. Use tasks.search to get the individual task records.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

tasks.toggleToggle Task StatusA

Flip a task line between [ ] and [x] in place, identified by sourceFile and 1-based lineNumber. When marking a task done, a ✅ YYYY-MM-DD date is stamped into the line (default today; override with doneDate). Fails if the target line is not a task checkbox. Use tasks.search to find the right sourceFile/lineNumber pair.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: lineNumber (required), sourceFile (required), doneDate, vaultPath. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

tasks.updateMetadataUpdate Task MetadataA
Idempotent

Update a task's dates, priority, or recurrence expression in place without touching the task body text. Identified by sourceFile + 1-based lineNumber. Pass only the fields you want to change. Idempotent — re-running with identical inputs converges on the same line. Fails if the target line is not a task.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: lineNumber (required), sourceFile (required), dueDate, priority, +4 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

templates.listList TemplatesA
Read-onlyIdempotent

List markdown templates in the vault's templates folder (or a folder of your choosing via templateFolder). Use this to discover what templates are available before calling templates.use. Read-only. Only returns markdown (.md) files.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Inputs: vaultPath, templateFolder. Returns: items, total

templates.useUse TemplateA

Render or apply a template using one of two engines. The engine field selects the engine and the action field selects the operation:

  • engine:'filesystem' — kObsidian's built-in {{variable}} substitution; no Obsidian plugin required. Actions: render (return the expanded text) or create-note (write a new note from the template).

  • engine:'templater' — delegate to the Templater Obsidian plugin via the Local REST API. Requires OBSIDIAN_API_URL and OBSIDIAN_REST_API_KEY. Actions: render (execute the template and return output), create-note (execute and write to targetFile), or insert-active (insert into the currently active note in Obsidian).

The filesystem engine is pure text substitution — it does NOT evaluate Templater's <% … %> scripts. Use engine:'templater' when you need dynamic evaluation.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Render a filesystem template to text (no file written):

{
  "engine": "filesystem",
  "action": "render",
  "templatePath": "Templates/daily.md",
  "variables": {
    "date": "2026-04-24",
    "topic": "kObsidian release planning"
  }
}

Example 2 — Create a new note from a filesystem template:

{
  "engine": "filesystem",
  "action": "create-note",
  "templatePath": "Templates/daily.md",
  "targetPath": "Journal/2026-04-24.md",
  "variables": {
    "date": "2026-04-24"
  }
}

Example 3 — Use Templater to create a note via the Obsidian plugin:

{
  "engine": "templater",
  "action": "create-note",
  "templateFile": "Templates/meeting.md",
  "targetFile": "Meetings/Kickoff.md",
  "openFile": true
}

Returns: Freeform object. The specific shape depends on the tool; see the tool description.

vault.currentCurrent Active VaultA
Read-onlyIdempotent

Return the vault that filesystem tools (notes., tags., dataview., blocks., canvas., kanban., marp., templates., tasks., links., wiki., stats.vault) would resolve to right now, plus the full precedence chain so the LLM can explain to the user why that vault was picked. reason is session-selected (vault.select was called), env-default (fell back to OBSIDIAN_VAULT_PATH), or none (nothing configured — tools will fail until vault.select or an env var is set). When OBSIDIAN_API_URL is configured, the response also carries an obsidianLiveInstance note reminding the caller that workspace. and commands.* tools target whichever vault the live Obsidian process has open, NOT the filesystem vault selected here. Read-only.

Inputs: no named parameters. Returns: Return shape of `vault.current`.

vault.listList Known VaultsA
Read-onlyIdempotent

List every Obsidian vault kObsidian knows about, merged and deduplicated across three sources: the operator's OBSIDIAN_VAULT_PATH (the default — always included), any OBSIDIAN_VAULT_=path env vars (explicit named vaults), and — when KOBSIDIAN_VAULT_DISCOVERY is on (the default) — the user's local Obsidian application registry at obsidian.json. Each item reports its source, isDefault, isActive, and exists so the LLM can flag stale or missing vaults. Pass refresh: true to force a fresh scan instead of using the 30s cache. Read-only. NOTE: the obsidian-app source is EXPERIMENTAL — it parses Obsidian's undocumented obsidian.json registry (stable since 1.0 but internal to Obsidian) and may silently stop returning results if Obsidian changes the format; the env-var sources are the documented, stable path.

Examples:

Example 1 — List vaults using the 30-second cache:

{}

Example 2 — Force a rescan (obsidian.json changed, new env vars added):

{
  "refresh": true
}

Inputs: refresh. Returns: Return shape of `vault.list`.

vault.resetReset Active Vault SelectionA
Idempotent

Clear the session-selected vault so the precedence chain falls back to OBSIDIAN_VAULT_PATH. Use this to signal 'I'm done with the scratch vault, go back to the default'. Idempotent — running on an already-cleared session is a no-op that reports changed: false. Does not change per-call vaultPath behaviour.

Inputs: no named parameters. Returns: Return shape of `vault.reset`.

vault.selectSelect Active VaultA

Set the session-active vault for subsequent filesystem tool calls. Identify the target by EXACTLY ONE of id (stable id from vault.list), name (case-insensitive match), or path (absolute directory path — need not appear in vault.list; lets the LLM point at a fresh/empty vault to initialise). Precedence chain becomes: per-call vaultPath argument (highest) → this session selection → OBSIDIAN_VAULT_PATH → error. Explicit vaultPath arguments on individual tool calls always override this selection. Respects KOBSIDIAN_VAULT_ALLOW / KOBSIDIAN_VAULT_DENY operator gating (though OBSIDIAN_VAULT_PATH is never filtered). Does NOT change which vault the live Obsidian process has open — workspace.* and commands.* tools remain tied to OBSIDIAN_API_URL. HTTP deployments: this server shares the selection across HTTP clients, so concurrent multi-client HTTP setups should pass vaultPath per call instead.

Examples:

Example 1 — Switch to the vault named 'Work':

{
  "name": "Work"
}

Example 2 — Select by id from vault.list:

{
  "id": "58f115bd2c2febd2"
}

Example 3 — Point at an ad-hoc path (e.g. a fresh vault to initialise):

{
  "path": "/Users/alice/FreshVault"
}

Inputs: id, name, path. Returns: Return shape of `vault.select`.

wiki.indexRebuildRebuild Wiki IndexA
DestructiveIdempotent

Regenerate wiki/index.md from a fresh scan of Sources/, Concepts/, and Entities/. Pages are grouped by category and sorted alphabetically; pass includeCounts:true to render counts on the section headings (e.g. ## Sources (12)). Idempotent and destructive — the existing index.md body is replaced wholesale, so any hand-edits there are lost. Use after bulk-creating pages outside the wiki tools, or as the cleanup step after wiki.lint reports indexMismatch. For incremental upkeep on a single source, prefer the proposedEdits returned by wiki.ingest instead.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Plain rebuild.:

{}

Example 2 — Rebuild with counts on each section heading.:

{
  "includeCounts": true
}

Inputs: wikiRoot, vaultPath, includeCounts. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

wiki.ingestIngest SourceA

File one new source into the wiki: writes Sources/<slug>.md with canonical frontmatter, appends an ingest entry to log.md, and returns a proposedEdits array the agent applies via existing notes.* tools (createStub → notes.create; insertAfterHeading / append → notes.edit with the matching mode). Cross-reference writes are deliberately NOT applied here so every edit shows up in the transcript. Provide either sourcePath (existing vault note) OR content (inline markdown) — never both. Use wiki.summaryMerge instead when you want to file a follow-up section into an EXISTING concept/entity page; use wiki.query to look something up without writing.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Ingest a paper from inline markdown with two related concepts and one entity.:

{
  "title": "In-Context Learning — A Survey",
  "content": "# In-Context Learning\n\nA survey of …",
  "sourceType": "paper",
  "url": "https://arxiv.org/abs/2301.00234",
  "tags": [
    "icl",
    "prompting"
  ],
  "relatedConcepts": [
    "In-Context Learning",
    "Few-Shot Prompting"
  ],
  "relatedEntities": [
    "Brown 2020"
  ]
}

Example 2 — Ingest an existing vault note as a 'note' source.:

{
  "title": "ADR-004 — gRPC for internal service comms",
  "sourcePath": "drafts/adr-004.md",
  "sourceType": "note",
  "tags": [
    "adr",
    "architecture"
  ]
}

Inputs: title (required), url, slug, tags, +11 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

wiki.initInitialize WikiA
Idempotent

Scaffold the LLM-Wiki layout under the vault: creates Sources/, Concepts/, Entities/ folders and seeds index.md, log.md, and wiki-schema.md (the schema reference the agent reads back later). Use this once per vault before calling any other wiki.* tool. Idempotent by default — existing files are preserved; pass force:true to re-seed index.md/log.md/wiki-schema.md (folders are never deleted). Returns { created: string[], skipped: string[] } so the agent can confirm what changed. Resolves the wiki location from wikiRoot arg → KOBSIDIAN_WIKI_ROOT env → wiki/.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — First-time scaffold in the active vault.:

{}

Example 2 — Re-seed schema/index/log files in a custom wiki directory.:

{
  "wikiRoot": "knowledge",
  "force": true
}

Inputs: force, wikiRoot, vaultPath. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

wiki.lintLint WikiA
Read-onlyIdempotent

Read-only health check across the wiki. Returns grouped findings under fixed keys: orphans (pages with zero in/out wiki-links), brokenLinks (links whose target does not resolve), staleSources and stalePages (older than staleDays, default 180 / KOBSIDIAN_WIKI_STALE_DAYS), missingPages (concept/entity names referenced from Sources but with no page), tagSingletons (tags used by exactly one page — likely typos), and indexMismatch (entries in index.md that no longer match disk). Each group includes a count plus per-finding details. Never writes. Use periodically; pair the result with notes.move/notes.edit/wiki.indexRebuild to apply fixes.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Default audit.:

{}

Example 2 — Stricter staleness threshold (90 days) for an active codebase wiki.:

{
  "staleDays": 90
}

Inputs: wikiRoot, staleDays, vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

wiki.logAppendAppend Wiki Log EntryA

Append one typed entry to wiki/log.md in the canonical format ## [YYYY-MM-DD] <op> | <title>, optionally followed by a body and a Refs: list. The format is chosen so grep '^## \[' log.md | tail -20 is a valid 'recent activity' query. Use this when the agent makes a wiki-meaningful action that no other wiki.* tool already logs (e.g. a decision or note); ingest and merge log themselves. Auto-runs wiki.init if the wiki has not been scaffolded yet. Idempotent only in the trivial sense — every call appends a new entry.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Log an architectural decision with two refs.:

{
  "op": "decision",
  "title": "Adopt gRPC for internal RPC",
  "body": "Streaming + typed schemas outweigh the browser-edge tax.",
  "refs": [
    "wiki/Sources/adr-004.md",
    "wiki/Concepts/grpc.md"
  ]
}

Example 2 — Quick freeform note dated today.:

{
  "op": "note",
  "title": "Reviewed orphan pages from last sprint"
}

Inputs: op (required), title (required), body, date, +3 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

wiki.queryQuery WikiA
Read-onlyIdempotent

Rank wiki pages by relevance to a free-text topic, scanning Sources/Concepts/Entities pages. Hits are weighted in this order: filename match > frontmatter aliases > frontmatter tags > frontmatter summary > body. Returns up to limit pages (default 10, max 50) as {path, type, score, hitFields} so the agent can drill into the strongest candidates with notes.read. Read-only; never writes. Use this for 'what does the wiki know about X?' lookups; use wiki.lint instead for whole-vault health audits, and notes.search for raw full-text search outside the wiki layout.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Top 10 pages relevant to 'memex vs hypertext'.:

{
  "topic": "memex vs hypertext"
}

Example 2 — Top 25 pages on a narrow topic, custom wiki dir.:

{
  "topic": "circuit breaker pattern",
  "limit": 25,
  "wikiRoot": "knowledge"
}

Inputs: topic (required), limit, wikiRoot, vaultPath. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

wiki.summaryMergeMerge Summary Into Concept Or Entity PageA

Add a cited section to an EXISTING Concepts/ or Entities/ page, or create the page with canonical frontmatter if targetPath does not exist. The new section is rendered under heading (default: Update YYYY-MM-DD); citationSource adds a [[wiki-link]] to the source and pushes it onto the page's sources: frontmatter list, and citationQuote renders as a blockquote under the citation. On existing pages, updated: frontmatter is bumped to today. Use this when filing a follow-up onto a known page; use wiki.ingest instead when bringing in a NEW source (which auto-creates Sources/<slug>.md). When creating a new entity page, entityKind is required.

Operates on the session-active vault (see vault.current — selectable via vault.select) unless an explicit vaultPath argument is passed, which always wins.

Examples:

Example 1 — Append a 'Notable Facts' section to an existing concept page, citing one source with a quote.:

{
  "targetPath": "wiki/Concepts/circuit-breaker.md",
  "heading": "Notable Facts",
  "newSection": "Adopted by payment-service after the 2026-04-10 cascade incident.",
  "citationSource": "wiki/Sources/postmortem-2026-04-10-payment-timeouts-cascade.md",
  "citationQuote": "Timeouts in payment-service propagated to order-service within 14s."
}

Example 2 — Create a new entity page for an organization on first reference.:

{
  "targetPath": "wiki/Entities/anthropic.md",
  "pageType": "entity",
  "entityKind": "org",
  "newSection": "AI safety lab; publisher of the Model Context Protocol.",
  "summary": "AI safety company behind Claude and MCP."
}

Inputs: newSection (required), targetPath (required), aliases, heading, +7 more. Returns: Standard mutation envelope. Individual tools may attach additional fields (e.g.…

workspace.activeFileGet Active FileA
Read-onlyIdempotent

Return information about the file currently open and focused in Obsidian — its path, modification time, and whether it's in edit or preview mode. Read-only. Requires the Local REST API plugin (OBSIDIAN_API_URL/OBSIDIAN_REST_API_KEY). Use this to orient the agent before issuing other workspace-level mutations.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Inputs: no named parameters. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

workspace.closeActiveFileClose Active FileA

Close whatever file is currently active in the Obsidian UI. UI-only — does not delete, save, or modify file contents. No-op when no file is active. Returns { ok: true } on success; errors when the Local REST API plugin is unreachable. Use after workspace.openFile when you want to dismiss a temporarily-revealed note. Pair with workspace.activeFile first if you need to know what was closed.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Examples:

Example 1 — Dismiss the currently active pane.:

{}

Inputs: no named parameters. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

workspace.navigateNavigate Obsidian HistoryA

Navigate the Obsidian back/forward file history, like the arrow buttons in the top-left. direction:'back' = back one step; direction:'forward' = forward one step. No-op when the stack is empty in the given direction. Requires the Local REST API plugin.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Inputs: direction (required). Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

workspace.openFileOpen File In ObsidianA

Open a vault-relative note filePath in the live Obsidian UI. newPane:true opens it in a new split; default reuses the active pane. UI-only — does not create, modify, or read file contents (use notes.read for content). Returns { ok: true } on success; errors when the file does not exist or the Local REST API plugin (OBSIDIAN_API_URL / OBSIDIAN_REST_API_KEY) is unreachable. The opened file targets the live Obsidian process's vault, which may differ from the filesystem session vault — see vault.current.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Examples:

Example 1 — Reveal a daily note in the current pane.:

{
  "filePath": "Daily/2026-04-25.md"
}

Example 2 — Open a reference note in a side split.:

{
  "filePath": "wiki/Concepts/grpc.md",
  "newPane": true
}

Inputs: filePath (required), newPane. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

workspace.toggleEditModeToggle Edit ModeA

Flip the active file in Obsidian between edit (source) mode and preview (reading) mode. Takes no arguments — always toggles whichever mode is currently active. UI-only: does not modify file contents. No-op when no file is active. Returns { ok: true, mode: 'edit' | 'preview' } reflecting the new mode; errors when the Local REST API plugin is unreachable. Useful when an agent has finished a multi-step edit and wants the user to see the rendered result.

Targets the vault the live Obsidian process has open via the Local REST API. Not affected by vault.select — that only changes filesystem-tool routing.

Examples:

Example 1 — Flip the active note from edit to preview (or vice versa).:

{}

Inputs: no named parameters. Returns: Freeform object. The specific shape depends on the tool; see the tool descripti…

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 66 tools

    Disambiguation4/5

    Tools are namespaced by domain (dataview, tasks, links, wiki, etc.) with clear action suffixes, so most are unambiguous. Minor overlap risk exists between similar utilities like links.hubs/links.connections/links.graph and dataview.query vs its sugar subcommands, but the descriptions clarify when to use each.

    Naming Consistency5/5

    All tool names follow a strict lowercase domain.action dotted convention (e.g., dataview.index, tasks.toggle, wiki.lint). No mixed casing or inconsistent separators. The one outlier 'kObsidian' in the server name is product branding, not a tool name.

    Tool Count3/5

    66 tools is a large surface. Many are justified (dataview sugar commands, per-link-type tools), but there's redundancy such as wiki.query/dataview.listByTag vs dataview.query, and links.hubs/links.connections/links.graph which all traverse the graph. Could be consolidated.

    Completeness4/5

    Covers the Obsidian ecosystem broadly: notes CRUD, tasks, dataview queries, links, blocks, workspace, wiki scaffolding, stats, and graph exploration. Missing a general vault-wide text search tool (a core Obsidian feature) and explicit dataview field update/write utilities; the bundle leans heavily read-only with a few mutations.

    Maintenance

    ActivityStale
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      This is a connector to allow Claude Desktop (or any MCP client) to read and search any directory containing Markdown notes (such as an Obsidian vault).
      837 npm
      1,352
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.
      3,713 npm
      751
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that implements Karpathy's LLM Wiki pattern for Obsidian vaults, enabling persistent knowledge storage and BM25 search across AI sessions.
      15 npm
      1
      MIT