kObsidian

kObsidian MCP

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

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

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

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

🧰 The only Obsidian MCP with workspaces. vault.list / vault.select

let an LLM discover and switch between your Obsidian vaults in-session —

no restart, no config edit, no per-tool path threading. Backwards

compatible with OBSIDIAN_VAULT_PATH. Added in v0.3.0.

See [docs/WORKSPACES.md](docs/WORKSPACES.md).

New in v0.3.7

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

Configuration example and upgrade notes.

Why kObsidian

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

Install

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

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

Claude Code — claude mcp add

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.

Claude Desktop — drag-and-drop .mcpb

Download kobsidian- .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 CLI (OpenAI) — codex mcp add

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

Cursor — ~/.cursor/mcp.json or deeplink

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

VS Code (Copilot) — code --add-mcp

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 CLI — gemini mcp add

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.

Antigravity (Google) — mcp_config.json

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

Zed — settings.json under context_servers

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

OpenCode — opencode.json under mcp

{

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

Factory Droid — droid mcp add

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

Other clients (Cline, JetBrains AI, Continue, custom hosts) — generic mcpServers JSON

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