Skip to content

obsidian-brain

Semantic search + knowledge graph + vault editing for Claude and any MCP client — over your Obsidian vault. Stdio-only, local embeddings, nothing hosted.

Get started Mac walkthrough (non-technical) GitHub

Install in 60 seconds

macOS one-liner — automates Homebrew + Node + the /usr/local/bin symlinks + the Claude Desktop config merge + Full Disk Access:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/sweir1/obsidian-brain/main/scripts/install.sh)"

Already have Node 20+? Drop this into Claude Desktop's config file at ~/Library/Application Support/Claude/claude_desktop_config.json instead:

{
  "mcpServers": {
    "obsidian-brain": {
      "command": "npx",
      "args": ["-y", "obsidian-brain@latest", "server"],
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}

Quit Claude (⌘Q), relaunch. First boot auto-indexes your vault and downloads a small embedding model — usually under a minute. That's it.

Config for Cursor, Claude Code, Jan, and 11 other clients → I'm not a developer — walk me through it →

What you get

  • Find

    Hybrid semantic + BM25 search over chunk-level embeddings, fused via Reciprocal Rank Fusion.

    search · list_notes · read_note

  • Map

    PageRank, Louvain community detection, shortest-path between any two notes in your vault.

    find_connections · find_path_between · detect_themes · rank_notes

  • Write

    Dry-run previews, atomic bulk edits, safe move_note that preserves inbound links and chunk embeddings.

    edit_note · create_note · move_note · link_notes · apply_edit_preview

  • Private by default

    Stdio-only — no network listener, no API keys, no outbound requests. Local embeddings via transformers.js. Your vault content never leaves the machine.

  • Fast

    SQLite + FTS5 + sqlite-vec. Microsecond reads, incremental indexing via filesystem watcher, debounced writes.

  • No plugin needed

    Reads .md files directly off disk. Obsidian doesn't need to be running. The companion plugin is optional — only for live-editor features.

  • Health & observability

    Fault-tolerant indexing (one bad chunk never halts the rebuild) + read-only index_status tool for coverage, failed chunks, capacity bounds, and reindex state.

    index_status · reindex

Why not just use Local REST API?

  • Obsidian can be closed — obsidian-brain reads .md files directly off disk, not through the Obsidian runtime.
  • Nothing to install inside Obsidian for the core feature set.
  • Chunk-level semantic search — LRA has no embeddings.
  • Graph analytics (PageRank, Louvain community detection, shortest-path) — LRA has no graph layer.
  • Stdio-only — no HTTP server, no port conflicts, no firewall prompts, no transport bugs.

Architecture deep-dive → · Tool reference → · Changelog →