obsidian-mcp

MCP server that wraps the official Obsidian CLI so an LLM agent can drive a running Obsidian instance — read/write notes, search, manage frontmatter, navigate links, run plugins, and more.

This server is a thin, comprehensive wrapper. Every tool maps 1:1 to an obsidian CLI command.

Prerequisites

1. Obsidian must be running. The CLI talks to the live app over IPC; it does not read the vault on disk directly.

2. Register the CLI binary. In Obsidian: Settings → General → Command line interface → Register CLI. Obsidian will add obsidian to your PATH.

3. Verify: obsidian version prints the CLI version.

Install

Two paths depending on whether you want to build it yourself or grab a pre-published version from npm.

Option A — Clone & build (works today)

Clone the repo and build locally, then point Claude Code at the built file:

git clone https://github.com/yuchichang/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build

Register it with Claude Code (one command):

# Add (user scope — available across all projects)
claude mcp add -s user obsidian -- node /absolute/path/to/obsidian-mcp/dist/index.js

# Remove
claude mcp remove obsidian

# List configured servers
claude mcp list

-s user registers it for your whole user account. Use -s project to commit it to the repo's .mcp.json instead, or -s local for the current project only (default).

Or write it into .mcp.json manually:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"]
    }
  }
}

Option B — Install from npm (zero-build)

Prerequisite: the package must already be published to npm. The maintainer publishes once via npm publish; all subsequent users get it via npx automatically. If you forked this repo and want this flow under your own scope, change name in package.json to @<your-npm-username>/obsidian-mcp, then npm publish.

Once published, no clone or build needed:

claude mcp add -s user obsidian -- npx -y @yuchichang/obsidian-mcp

Or in .mcp.json / Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@yuchichang/obsidian-mcp"]
    }
  }
}

Override the CLI path

If obsidian isn't on PATH, set the OBSIDIAN_CLI env var. Works with either install path:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_CLI": "C:/Users/you/AppData/Local/Obsidian/obsidian.cmd"
      }
    }
  }
}

Tools

Vault & files

Frontmatter properties

Search

Tags & links

Daily notes

Plugins

Developer / advanced

Meta

Conventions

• Targeting a note — file-targeting tools accept either:

  • file — wikilink-style note name (e.g. "My Note"), or

  • path — vault-relative file path (e.g. "Folder/My Note.md").

• Multi-vault setups — every tool accepts an optional vault parameter. When omitted, the most recently focused vault is used.

• Output format — list/search/metadata tools default to JSON for easy machine parsing.

Sensitive operations & user confirmation

The following tools are gated behind a user-confirmation step:

How the gate works:

1. MCP elicitation (preferred). If the connected client supports the elicitation capability (Claude Code does), the server sends an elicitation/create request and the client shows the user a Proceed? prompt with the action and target spelled out. Only accept + confirm: true proceeds.

2. Explicit confirm: true parameter. Every sensitive tool's input schema includes an optional confirm: boolean. Passing confirm: true skips the elicitation prompt — use this only when the caller has already obtained user approval.

3. Refusal fallback. If the client doesn't support elicitation and confirm: true was not provided, the tool returns an isError result that names the action and instructs the caller to retry with confirm: true.

Bypass for batch / automation

OBSIDIAN_MCP_AUTO_CONFIRM=1

Set this env var (in your MCP client's env block) to skip every confirmation prompt. Use only in fully-trusted automation contexts.

Topic → folder routing (vault-aware, persistent)

The MCP runs a per-vault topic store at ~/.obsidian-mcp/<vault>/topic-map.json. It learns where each topic of note belongs and reuses that decision next time.

Agent: create_note(path="kungpao.md", topic="recipe-chinese", vault="MyVault")
   ↓
MCP: is "recipe-chinese" already in the store?
   ├── yes → use the stored folder, increment usage, write
   └── no  → scan vault for similar folders ("Recipes/Chinese", "食譜/中式" …)
            → MCP elicits the user: "Where should 'recipe-chinese' notes live?
              Suggestions: ..."
            → user types or picks a folder
            → MCP records the route, then writes

What lives where, and why:

• The persistent store, not env vars, is the source of truth — the MCP is the only thing that sees vault state across sessions, so storing the conventions there is what gives this layer its leverage.

• The user is asked once per topic; subsequent notes for the same topic land silently.

• Folders are auto-created by the Obsidian CLI as deep as needed — no mkdir from the MCP.

Resolution order

Topic-store tools

Theory pointers

Faceted folder routing here is the simplest slice of a much larger idea. Worth reading if you want to push further:

• Ranganathan, S.R. (1933) Colon Classification — PMEST facets

• Ranganathan, S.R. (1931) Five Laws of Library Science

• Tiago Forte (2022) Building a Second Brain — PARA method (actionability axis)

• Niklas Luhmann (1981) "Kommunikation mit Zettelkästen" — graph-over-tree

• Bates, M.J. (1989) "The design of browsing and berrypicking"

Bulk organize root notes

When the vault root accumulates loose .md files, a caller LLM can sweep them into the right subfolders in three steps:

1. Scan — list root notes with metadata + body preview:

   // tool: obsidian_scan_root
   { "ignore": ["Daily/*", "*.excalidraw.md"] }

2. Classify (caller side) — the LLM reads each preview and proposes a routing plan:

   [
     { "path": "WebRTC 連線建立流程.md", "target_folder": "webrtc", "topic": "webrtc", "reason": "covers signaling/SDP/ICE" },
     { "path": "舊筆記.md", "target_folder": "Notes", "topic": "misc" }
   ]

3. Apply — dry-run first to preview, then call again with dry_run: false:

   // tool: obsidian_organize_apply
   { "plan": [...], "dry_run": true }
   // → { "summary": { "will_move": 2, "will_create_folders": 1, ... }, "items": [...] }
   
   { "plan": [...], "dry_run": false, "confirm": true }
   // → moves files, creates new folders as needed, registers topic→folder mappings

Per-entry failure isolation: a single move failure marks that entry status: "failed" without aborting the rest of the batch. Successful moves with a topic field are recorded in the persistent topic store, so future single-note writes for that topic auto-route.

Long content & argv limits

The Obsidian CLI does not (yet) support reading parameter values from stdin or from files — every value travels on the command line. That collides with platform limits:

To stay safe, the server automatically chunks long writes:

Splits happen at line boundaries when possible; oversized single lines fall back to UTF-8-safe character boundaries. Reassembled content is byte-identical to the original.

Configure the per-call byte threshold (defaults: 6,000 on Windows, 100,000 elsewhere):

OBSIDIAN_MCP_MAX_ARG_BYTES=4000

If a chunk in the middle of a multi-chunk write fails, the server returns isError with a clear message stating which chunks made it to disk so the caller can recover.

Develop

npm run dev      # tsc --watch
npm run inspect  # launch MCP Inspector against the built server
node scripts/smoke-test.mjs   # initialize + tools/list smoke test

How it works

runObsidian() (src/exec.ts) shell-quotes arguments, invokes the obsidian binary via child_process.exec, and parses stdout. Most read-style tools request format=json; results are parsed to structuredContent for clients that consume structured tool output, while still returning a text representation in content.

Tool registry lives in src/tools.ts — adding a new wrapped command is a single entry there.

Reference

• Obsidian CLI: https://obsidian.md/help/cli

• MCP spec: https://modelcontextprotocol.io