kObsidian MCP
kObsidian MCP is a filesystem-first MCP server for Obsidian vaults with 90+ tools across 16 namespaces, plus an LLM-Wiki layer and optional live Obsidian UI control via the Local REST API plugin.
Notes & Folders: Read, create, update, delete, move, search, and list notes/folders; insert after headings/blocks, append content, update frontmatter, get metadata and statistics.
Tags: Add, remove, update, search, and list tags across the vault (with counts); analyze frontmatter and inline tags per note.
Links: Find backlinks, outgoing links, broken links, and orphaned notes; build a full vault link graph; identify hub notes; analyze link health; explore multi-hop connections.
Tasks (Tasks-plugin format): Search with filters (status, priority, due date, tags, recurrence), create with full metadata, toggle complete/incomplete, update in-place, get aggregate stats.
Dataview: Extract/search/add/remove Dataview fields (frontmatter, inline, list, task); read/update fenced DQL and DataviewJS blocks; execute live DQL queries (list by tag/folder, table queries) via the Obsidian API.
Mermaid Blocks: List, read, and update fenced Mermaid diagram blocks.
Marp Presentations: Read full decks (frontmatter, slides, directives); list/read/update individual slides and deck frontmatter.
Kanban Boards: Parse boards; add, move, and toggle cards between columns; get card counts and completion stats.
Canvas Files: Create, parse, and edit .canvas files; add/remove text or file nodes and edges; explore node connections.
Templates: List templates, expand filesystem template variables, create notes from templates, render/create/insert Templater templates via the Obsidian API.
Live Obsidian Workspace (requires Local REST API plugin): Get the active file, open/close files, navigate history, toggle edit/preview mode, list/search/execute Obsidian commands.
LLM Wiki Layer: Initialize a structured wiki (Sources/, Concepts/, Entities/), ingest sources, append chronological log entries, rebuild the wiki index, query pages by topic relevance, lint for orphans/broken links/stale pages/missing concepts/tag singletons/index mismatches, and merge summaries into concept/entity pages. Wiki content is also accessible via MCP resources (kobsidian://wiki/*).
Vault & System: Multi-vault discovery, selection, and switching; per-note and vault-wide statistics; server version and runtime info. All tools support optional per-call vault selection and are annotated with read-only, destructive, idempotent, and open-world hints.
Provides filesystem-first access to Obsidian vaults, enabling AI agents to read, write, and manage notes, links, tags, tasks, and more using 90 MCP tools. Supports both local filesystem operations and REST API bridging for workspace and command tools when the Obsidian Local REST API plugin is enabled.
kObsidian MCP
Filesystem-first MCP server for Obsidian vaults — with an LLM-Wiki layer on top.
Inspired by Andrej Karpathy's LLM Wiki idea. You curate the sources; the LLM does the bookkeeping.
Install · Quick start · Architecture · LLM Wiki · Tools · Docs
🧰 The only Obsidian MCP with workspaces.
vault.list/vault.selectlet an LLM discover and switch between your Obsidian vaults in-session — no restart, no config edit, no per-tool path threading. Backwards compatible withOBSIDIAN_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
structuredContentoutput and the full 4-hint MCP annotation set (readOnlyHint,destructiveHint,idempotentHint,openWorldHint).Multi-vault
vault.*(v0.3.0). The LLM canvault.listyour known Obsidian vaults (discovered from Obsidian's own registry orOBSIDIAN_VAULT_<NAME>env vars) andvault.selectbetween them for the session. Fully backwards compatible:OBSIDIAN_VAULT_PATHstays the default and per-callvaultPatharguments 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 aproposedEditscontract 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-Versionhandling, 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.mcpbbundles for Claude Desktop drag-and-drop, asmithery.yamlfor Smithery, and aserver.jsonfor the MCP Registry. Each.mcpbrelease 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 |
| Required everywhere. Absolute path to the vault. |
| Base URL of the Local REST API plugin. Default |
| Optional. Defaults to |
| Local REST API plugin bearer key — only for |
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-mcpOn 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.mcpbcodex 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-mcpEdit ~/.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-mcpOr 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-toolsAny 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:httpObsidian 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:
Open your vault in Obsidian.
Settings (⚙️, bottom-left) → Community plugins.
Click Turn on community plugins.
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 offlinedataview.fields.*/dataview.index/blocks.*tools work without it)templates.usewithengine: "templater"
Setup after install:
Enable the plugin.
Open its settings — scroll to API key → click Copy (or Reset first if you want a fresh one).
Paste that key as
OBSIDIAN_REST_API_KEYin your MCP client config'senv:block. TheOBSIDIAN_API_URLdefault (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 |
| All | |
| Runtime template rendering via the REST API ( | |
| Marp | |
|
| |
|
|
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 | Just a vault path. No plugins required. |
Use | + Local REST API plugin + API key env var |
Run live DQL queries ( | + 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 confirmFull 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
proposedEditscontract 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 …) makesgrep '^## \[' wiki/log.md | tail -20a valid "what did the team decide recently" query.wiki.lintsurfaces 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 pageDefault 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 contractThe 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 |
| 4 |
|
| 8 |
|
| 4 |
|
| 8 | Backlinks · outgoing · broken · orphans · hubs · graph · health · connections |
| 1 |
|
| 5 | Tasks-plugin format (📅 ⏳ 🛫 ✅ 🔼 🔁) — search · create · toggle · updateMetadata · stats |
| 7 |
|
| 3 | Unified fenced-block API ( |
| 2 |
|
| 3 |
|
| 4 |
|
| 2 |
|
| 5 | Live Obsidian UI bridge (requires Local REST API plugin) |
| 2 |
|
| 7 | init · ingest · log · indexRebuild · query · lint · summaryMerge |
| 1 |
|
Client-safety annotations (MCP 2025-11-25):
Hint | Tools |
| 47 |
| 6 |
| 12 |
| 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 pageMCP 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 |
| — | Required. Absolute path to the vault. |
|
| Obsidian Local REST API base; only for |
|
| Set |
| — | Bearer key for the REST API plugin (if used). |
|
| Bind host for |
|
| Bind port for |
| — | Optional bearer for the Streamable HTTP transport. |
|
| Comma-separated CORS allowlist. |
|
| Wiki directory under the vault. |
|
| Per-source summary pages. |
|
| Topic / idea pages. |
|
| People / places / orgs / works. |
|
| Wiki catalog filename. |
|
| Wiki log filename. |
|
| Seed schema filename. |
|
|
|
|
|
|
|
|
|
|
|
|
|
| Concept-page heading that receives |
|
| Entity-page heading that receives |
|
| 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 한국어.
Stack, module map, layering rules | |
LLM-Wiki contract, loop, frontmatter, lint categories | |
Personal research wiki · engineering ADRs · codebase wiki — end-to-end | |
Namespace table, annotations, resources, prompts | |
Origin/CORS, VirusTotal scans, env hygiene | |
| |
Every env var with defaults | |
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.crossChecktool that reconciles two or more LiveSync-paired vaults at the wiki layer, gated by a newschema_versionfrontmatter 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.jsonProject conventions in AGENTS.md.
Security & supply chain
Every
.mcpbrelease asset is VirusTotal-scanned. TheReleaseworkflow uploads eachkobsidian-<platform>.mcpbbundle to VirusTotal viacrazy-max/ghaction-virustotal@v4right 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
Originagainst an allowlist (403 on mismatch), implements CORS preflight (OPTIONS /mcp→ 204 +Access-Control-*), requires or defaultsMCP-Protocol-Version, and supports optional bearer auth viaKOBSIDIAN_HTTP_BEARER_TOKEN. stdio has no network surface.Pinned SDK floor.
@modelcontextprotocol/sdk@^1.26.0— mitigatesGHSA-345p-7cg4-v4c7(cross-client response leak) andCVE-2026-0621(UriTemplate ReDoS). This repo pins1.30.0.npm Trusted Publishing. No long-lived
NPM_TOKENis 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.ymlon thebezata/kObsidianrepo). 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 withoutMCP-Protocol-Versionfall back to2025-03-26per spec; explicit-but-unsupported versions return 400.Dataview split — offline tools index frontmatter / inline / list / task / fenced
dataview/ fenceddataviewjsblocks. 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(mitigatesGHSA-345p-7cg4-v4c7cross-client response leak +CVE-2026-0621UriTemplate ReDoS). This repo pins1.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.
Available Tools
66 toolsblocks.listList Fenced BlocksARead-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 BlockARead-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 BlockADestructiveIdempotent
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 ConnectionsARead-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 CanvasARead-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 CommandADestructive
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 CommandsARead-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 FieldsARead-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 FieldsAIdempotent
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 IndexARead-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 FolderARead-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 TagARead-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 QueryARead-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 QueryARead-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 BoardARead-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 StatisticsARead-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.backlinksGet BacklinksARead-onlyIdempotent
Find every note that links TO a target note (inbound references). Supports both wiki-style [[Note]] and markdown-style [text](Note.md) links. When includeContext:true, each result carries a contextLength-char snippet of surrounding text so the agent can judge link intent without re-reading each source. Read-only. For outbound links (what a note points AT), use links.outgoing.
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, contextLength, includeContext. Returns: Standard list envelope used by list/search tools.
links.brokenFind Broken LinksARead-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 ConnectionsARead-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 GraphARead-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 HealthARead-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 NotesARead-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 NotesARead-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 LinksARead-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 DeckARead-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 DeckADestructiveIdempotent
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 NoteADestructive
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 FrontmatterAIdempotent
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 FoldersARead-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 FolderADestructiveIdempotent
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 NoteARead-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 NotesARead-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 StatisticsARead-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 VersionARead-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 TagsARead-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 TagsARead-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 TagsAIdempotent
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 TagARead-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 TasksARead-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 StatisticsARead-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 MetadataAIdempotent
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 TemplatesARead-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) orcreate-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 totargetFile), orinsert-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 VaultARead-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 VaultsARead-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 SelectionAIdempotent
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 IndexADestructiveIdempotent
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 WikiAIdempotent
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 WikiARead-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 WikiARead-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 FileARead-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.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
Scored across 66 tools
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.
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.
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.
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
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
An MCP server that gives your AI access to the source code and docs of all public github repos
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceThis 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 npm1,352AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.3,713 npm751MIT
- AlicenseAqualityCmaintenanceLocal-first MCP server for working with an Obsidian vault. No API key required1719MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that implements Karpathy's LLM Wiki pattern for Obsidian vaults, enabling persistent knowledge storage and BM25 search across AI sessions.15 npm1MIT