Skip to content

Quick start

No clone, no build. Requires Node 20+ and an Obsidian vault (or any folder of .md files — Obsidian itself is optional).

Minimum config

Wire obsidian-brain into your MCP client. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Quit Claude Desktop (⌘Q on macOS) and relaunch. That's it.

For every other MCP client (Claude Code, Cursor, VS Code, Jan, Windsurf, Cline, Zed, LM Studio, Opencode, Codex, Gemini CLI, Warp, JetBrains AI), see Install in your MCP client.

First boot

On first launch the server auto-indexes your vault and downloads the embedding model (~34 MB for the default bge-small-en-v1.5). Initial tools/list may block for 30–60 s — subsequent starts are instant. See Architecture → indexing for why.

No system-level prerequisites beyond Node 20+. The better-sqlite3, sqlite-vec, and ONNX runtime native bindings ship as prebuilt binaries for macOS, Linux, and Windows — no brew install sqlite, no Xcode Command Line Tools, no Python required.

Environment variables

All configuration is via environment variables. Only VAULT_PATH is required.

Variable Required Default Description
VAULT_PATH yes — Absolute path to the vault (folder of .md files).
DATA_DIR no $XDG_DATA_HOME/obsidian-brain or $HOME/.local/share/obsidian-brain Where the SQLite index + embedding cache live.
EMBEDDING_PRESET no english Preset name. Options: english (default, Xenova/bge-small-en-v1.5), fastest, balanced, multilingual. See README for details. Ignored if EMBEDDING_MODEL is set.
EMBEDDING_MODEL no (resolved from preset) Power-user override: any transformers.js checkpoint (with EMBEDDING_PROVIDER=transformers) or Ollama model name (with EMBEDDING_PROVIDER=ollama). Takes precedence over EMBEDDING_PRESET. Switching models (or providers) triggers an automatic reindex on next boot — no --drop required.
EMBEDDING_PROVIDER no transformers Embedder backend: transformers (local, zero setup) or ollama (routes through a local Ollama server via /api/embeddings, v1.5.0+).
OLLAMA_BASE_URL no http://localhost:11434 Only read when EMBEDDING_PROVIDER=ollama.
OLLAMA_EMBEDDING_DIM no unset Declared output dim for the Ollama model. If unset, the server probes the model on first startup.
OBSIDIAN_BRAIN_NO_WATCH no unset Set to 1 to disable the live watcher and fall back to scheduled re-indexing.
OBSIDIAN_BRAIN_NO_CATCHUP no unset Set to 1 to disable the startup catchup reindex.
OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS no 3000 Per-file reindex debounce for the watcher.
OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS no 60000 Graph-wide community-detection debounce.
OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS no 30000 Per-tool-call timeout.

KG_VAULT_PATH is accepted as a legacy alias for VAULT_PATH.

Next steps