Obsidian Native MCP

LLM-optimized MCP server for Obsidian vaults Surgical edits, hash-based concurrency safety, no whole-file rewrites.

A Model Context Protocol server that gives AI assistants (Claude Desktop, Cursor, Rovo Dev, etc.) direct, safe, context-efficient access to your Obsidian vaults.

Two ways to use it:

• Obsidian plugin — 1-click install, auto-discovers vaults, settings UI for per-tool toggles, runs inside Obsidian over HTTP/SSE with a bearer token.

• CLI — standalone Node binary, configured via env var or config file, speaks JSON-RPC over stdio with Content-Length framing.

Why Obsidian Native MCP

The defining design goal is minimize how many bytes the LLM has to push around per edit. Every read returns content plus cryptographic hashes; every write declares the precondition hash it expects. The result: most edits become tiny str_replaces or unified-diff patches instead of full file rewrites.

Installation

Obsidian plugin (recommended)

1. Open Obsidian → Settings → Community Plugins → Browse

2. Search for "Native MCP" and install

3. Enable in Community Plugins

4. Open plugin settings: select which vaults to expose, optionally toggle per-tool permissions, copy the MCP URL

CLI (standalone)

npm install -g obsidian-native-mcp

Build from source

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

Configuration

Plugin

Auto-discovers all your Obsidian vaults from Obsidian's own config. Pick which to expose in plugin settings. Plugin also surfaces a bearer token and the MCP URL.

A Performance budgets section in plugin settings lets you cap long-running operations. All limits default to 0 = unlimited — raise or lower them freely without restriction.

CLI

Either an env var or a config file.

# Single vault
export OBSIDIAN_VAULT_PATHS=/Users/me/my-obsidian-vault

# Multiple vaults (semicolons on all platforms)
export OBSIDIAN_VAULT_PATHS=/Users/me/personal;/Users/me/work

Config file at ~/.config/obsidian-native-mcp/vaults.json:

{
  "vaults": {
    "personal": "/Users/me/personal-notes",
    "work": "/Users/me/work-vault"
  }
}

Optional flags:

obsidian-native-mcp --read-only            # all write tools disabled
obsidian-native-mcp --vault notes=/path    # ad-hoc named vault
obsidian-native-mcp --config ./my.json     # explicit config file

Performance budget env vars

All default to 0 (unlimited). Set any to a positive integer to cap that resource:

MCP_MAX_FILES_SCANNED=500    # files per search.content / vault.info call
MCP_MAX_BYTES_READ=10000000  # raw bytes per call (~10 MB)
MCP_MAX_BULK_OPS=50          # ops per bulk.apply call
MCP_DEADLINE_MS=30000        # wall-clock ms ceiling for long-walk tools

These are defaults — they are never enforced as hard system limits. Set them to whatever makes sense for your vault and workflow.

Usage

Obsidian plugin

Add the URL from plugin settings to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-native-mcp": {
      "url": "http://127.0.0.1:9789/sse?token=YOUR_TOKEN"
    }
  }
}

CLI

{
  "mcpServers": {
    "obsidian-native-mcp": {
      "command": "obsidian-native-mcp",
      "env": {
        "OBSIDIAN_VAULT_PATHS": "/Users/me/my-obsidian-vault"
      }
    }
  }
}

Tools

All tools accept an optional vault parameter; with a single vault configured, it's inferred. Every read returns hashes used by writes as preconditions.

Read tools

Write tools — surgical primaries

Write tools — structural (when you have the address)

Write tools — whole-file & metadata

Power & batch

Per-call budget overrides (_budget)

vault.info, search.content, and bulk.apply all accept an optional _budget object that overrides the server-level config for that single call only. This lets an AI agent tighten or relax limits based on what it knows about the task:

{
  "tool": "search.content",
  "arguments": {
    "query": "important term",
    "directory": "Projects/",
    "_budget": {
      "maxFilesScanned": 200,
      "maxBytesRead": 5000000,
      "deadlineMs": 10000
    }
  }
}

When a budget is hit, the tool returns truncated: true with a hint and (for search.content) a nextOffset the agent can use to resume pagination. No error is thrown — the agent gets partial results and can decide what to do next.

Prompts

Place markdown in any vault's Prompts/ folder with mcp-tools-prompt in the frontmatter; Templater-style <% tp.mcpTools.prompt(name, hint) %> placeholders become MCP prompt arguments automatically.

Concurrency safety

Every read returns one or more hashes. Every write that operates on an existing range requires the matching expected_*_hash. If the file changed underneath you (a human edit in Obsidian, a parallel tool call, etc.), the write returns:

{
  "ok": false,
  "error": {
    "code": "STALE_PRECONDITION",
    "current_content_hash": "sha256:…",
    "current_section_hash": "sha256:…"
  }
}

The model refreshes from the new hash and retries. No silent clobbering.

Permissions

• Read-only mode — plugin toggle or CLI --read-only flag disables every write tool.

• Per-tool toggle — disable individual tools (e.g., turn off file.delete for less-trusted clients).

• Per-vault subdir allow/deny — limit a client to a vault subtree.

Audit log

Every mutating call appends one JSONL line to <vault>/.obsidian/plugins/native-mcp/audit.log:

{
  "ts": "2026-05-21T13:00:00Z",
  "tool": "str_replace",
  "vault": "notes",
  "file": "Daily/2026-05-21.md",
  "args_hash": "sha256:…",
  "before_hash": "sha256:…",
  "after_hash": "sha256:…",
  "dry_run": false,
  "ok": true
}

Long-walk tools (search.content, vault.info) also emit telemetry fields:

{
  "ts": "2026-05-21T13:00:01Z",
  "tool": "search.content",
  "vault": "notes",
  "duration_ms": 412,
  "files_scanned": 347,
  "bytes_read": 2891024,
  "truncated": true,
  "abort_reason": "budget"
}

Rotates at 5 MB by default.

Security

• Runs locally only — loopback (127.0.0.1) for HTTP, stdio for CLI.

• HTTP transport requires a startup-generated bearer token in the SSE URL.

• Origin header allowlist enforced; CORS is not *.

• Request bodies capped at 5 MB; max-sessions and idle TTL applied.

• Path-traversal protection on every vault-relative path.

• Only vaults you explicitly select are accessible.

License

MIT