VAULT_PATH — Absolute path to your Obsidian vault (or any folder of .md files).
DATA_DIR — Where to store the SQLite index + embedding cache. Defaults to $XDG_DATA_HOME/obsidian-brain or ~/.local/share/obsidian-brain.
EMBEDDING_PRESET — Preset name: english (default, bge-small-en-v1.5), english-fast, english-quality, multilingual, multilingual-quality, multilingual-ollama. Ignored when EMBEDDING_MODEL is set.
EMBEDDING_MODEL — Power-user override: any transformers.js checkpoint or Ollama model id. Takes precedence over EMBEDDING_PRESET. Switching auto-reindexes.
EMBEDDING_PROVIDER — Embedding backend. 'transformers' (local, default) or 'ollama' (requires a running Ollama server).
OLLAMA_BASE_URL — Base URL of a local Ollama server. Only used when EMBEDDING_PROVIDER=ollama.
OLLAMA_EMBEDDING_DIM — Override the embedding dimensionality when EMBEDDING_PROVIDER=ollama. If unset, the server probes the model on startup.
OLLAMA_NUM_CTX — Override Ollama's num_ctx for embed requests. Leave UNSET to let obsidian-brain auto-detect via `/api/show`'s `context_length` (e.g. nomic-embed-text=2048, bge-m3=8192, qwen3-embedding:0.6b=32 768). Setting this manually imposes a hard cap and may silently truncate longer inputs — see https://github.com/ollama/ollama/issues/14259. Ollama's own default is 2048 which truncates for any model trained on a larger context. See also https://github.com/ollama/ollama/issues/7008. Fallback when both env is unset AND /api/show is unreachable: 8192.
OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL — Auto-pull the configured Ollama model when /api/show returns 404 (model not present). Default ON — choosing an Ollama-backed preset is implicit consent to download its model. Streams /api/pull progress to stderr. Set to '0' to disable auto-pull entirely (master kill-switch) and fall back to the actionable error path (`HTTP 404 — try: ollama pull <model>`).
OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL — Opt-in to auto-pull for BYOM (custom EMBEDDING_MODEL) Ollama models OUTSIDE Ollama's official `library/` namespace. Default OFF — third-party models (e.g. `user/custom-fork`, `myregistry.com/team/model`) require this env var to be set to `1` before they will auto-pull, to prevent silent downloads of arbitrary user-named artifacts. Preset-known models (via EMBEDDING_PRESET) and bare model ids in the official library (e.g. `qwen3-embedding:0.6b`, `library/llama3:8b`) continue to auto-pull by default per the existing OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL behavior.
OBSIDIAN_BRAIN_NO_WATCH — Set to '1' to disable the live chokidar file watcher. Useful on SMB/NFS vaults where FSEvents/inotify don't fire reliably — fall back to running `obsidian-brain index` on a schedule (launchd/systemd).
OBSIDIAN_BRAIN_NO_CATCHUP — Set to '1' to skip the startup catchup reindex pass that picks up edits made while the server was down. The live file watcher still starts (via OBSIDIAN_BRAIN_NO_WATCH=1 to disable that separately), and first-time indexing on an empty DB is unaffected — this knob only governs the post-restart `enqueueBackgroundReindex` walk.
OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS — Per-file reindex debounce for the live watcher, in milliseconds.
OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS — Graph-wide community-detection (Louvain) debounce for the live watcher, in milliseconds. Louvain is the only expensive op — batching it prevents per-edit CPU spikes.
OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS — Per-tool-call timeout in milliseconds. Tools exceeding this return an MCP error instead of hanging.
OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS — Override the adaptive chunk-size budget (in tokens). When set, this beats the capacity probed from the model's tokenizer or Ollama /api/show. Use for debugging or for models with stale tokenizer configs.
OBSIDIAN_BRAIN_CONFIG_DIR — Override the per-user config directory where obsidian-brain stores model overrides (`model-overrides.json`) and the user-fetched seed (`seed-models.json`). Default is `$XDG_CONFIG_HOME/obsidian-brain` on macOS/Linux (or `~/.config/obsidian-brain`) and `%APPDATA%/obsidian-brain` on Windows. Both files survive `npm update obsidian-brain` because they live outside the package.
OBSIDIAN_BRAIN_DEBUG — Set to "1" to print a verbose synchronous startup trace to stderr — every preflight, createContext, server.connect, and shutdown step is logged with a monotonic timestamp. The LAST line before any silent failure tells you exactly which step the server reached. No-op when unset (no overhead). Use to diagnose silent-crash failure modes.
OBSIDIAN_BRAIN_LOG_FORMAT — Set to 'ndjson' for one-JSON-object-per-line stderr output (timestamp + level + message + structured fields). Default is human-readable plain text (`obsidian-brain: <message>`). Useful for piping logs into aggregators (Datadog, Loki, Vector, journald) that index structured fields.
Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
A standalone Node MCP server that gives Claude (and any other MCP client) over an Obsidian vault. Runs as one local stdio process — no plugin, no HTTP bridge, no API key, nothing hosted. Your vault content never leaves your machine.
Obsidian MCP server: semantic search, knowledge graph, and vault editing. No plugin required.
รันบน PlugMCP
Host a copy with our keys and logs.
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Works without Obsidian running — unlike Local REST API-based servers, obsidian-brain reads .md files directly from disk. Obsidian can be closed; your vault is just a folder.
No Local REST API plugin required — nothing to install inside Obsidian for the core experience.
Chunk-level semantic search with RRF hybrid retrieval — embeddings at markdown-heading granularity, fused with FTS5 BM25 via Reciprocal Rank Fusion. Finds the exact chunk, ranks on meaning.
The only Obsidian MCP server with PageRank + Louvain + graph analytics — ask for your vault's most influential notes, bridging notes, theme clusters. Nobody else ships this.
Ollama provider for high-quality local embeddings — switch to qwen3-embedding:0.6b, nomic-embed-text, bge-m3, etc. with one env var.
All in one npx install — no clone, no build, no API key, no hosted endpoint. Vault content never leaves your machine.
Installs Homebrew + Node 20+ if you don't already have them, adds the /usr/local/bin symlinks that Claude Desktop needs, merges obsidian-brain into your claude_desktop_config.json, opens the Full Disk Access pane for you to toggle Claude on, and relaunches Claude. You'll be asked for your macOS password once (for Homebrew + the symlinks) and your vault path once. Everything else is automatic. Audit what it does: scripts/install.sh.
Manual install
Requires Node 20+ and an Obsidian vault (or any folder of .md files — Obsidian itself is optional).
Wire obsidian-brain into your MCP client. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
Quit Claude Desktop (⌘Q on macOS) and relaunch. That's it.
[!NOTE]
On first boot the server auto-indexes your vault and downloads a ~34 MB embedding model. Tools may take 30–60 s to appear in the client. Subsequent boots are instant.
[!TIP]
Not a developer? The macOS walkthrough covers Homebrew, Node, the GUI-app PATH fix, and Full Disk Access step-by-step.
For every other MCP client (Claude Code, Cursor, VS Code, Jan, Windsurf, Cline, Zed, LM Studio, JetBrains AI, Opencode, Codex CLI, Gemini CLI, Warp): see Install in your MCP client.
Live editor (requires companion plugin) — active_note, dataview_query, base_query
Maintenance — reindex, index_status
→ Arguments, examples, and response shapes: Tool reference
How it works
flowchart LR
Client["<b>MCP Client</b><br/>Claude Desktop · Claude Code<br/>Cursor · Jan · Windsurf · ..."]
subgraph OB ["obsidian-brain (Node process)"]
direction TB
SQL["<b>SQLite index</b><br/>nodes · edges<br/>FTS5 · vec0 embeddings"]
Vault["<b>Vault on disk</b><br/>your .md files"]
Vault -->|"parse + embed"| SQL
SQL -.->|"writes"| Vault
end
Client <-->|"stdio JSON-RPC"| OB
Retrieval and writes both go through a SQLite index: reads are microsecond-cheap, writes land on disk immediately and incrementally re-index the affected file. Embeddings are chunk-level (heading-aware recursive chunker preserving code + LaTeX blocks), and search's default hybrid mode fuses chunk-level semantic rank with FTS5 BM25 via Reciprocal Rank Fusion.
An optional Obsidian plugin at sweir1/obsidian-brain-plugin exposes live Obsidian runtime state — active editor, Dataview results, Bases rows — over a localhost HTTP endpoint. When installed and Obsidian is running, active_note, dataview_query, and base_query light up. Install via BRAT with repo ID sweir1/obsidian-brain-plugin.
Ship plugin and server at the same major.minor — server v1.7.x pairs with plugin v1.7.x. Patch-version drift is fine.
"Connector has no tools available" in Claude Desktop — usually the server crashed at startup. Check ~/Library/Logs/Claude/mcp-server-obsidian-brain.log. Fix: npm install -g obsidian-brain@latest, quit Claude (⌘Q), relaunch.
ERR_DLOPEN_FAILED / NODE_MODULE_VERSION mismatch — better-sqlite3 built against a different Node ABI. Fix: PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
Vault path not configured — VAULT_PATH is unset. Set it in the env block of your client config or shell.
Old version loading via npx (your client still shows the previous release after a publish) — stale npx cache. Fix: rm -rf ~/.npm/_npx, then restart your client. Keeping @latest in your config prevents this.
→ Full troubleshooting guide (watcher not firing, stale index, running multiple clients, timeouts, embedding-dim mismatch, log locations): docs/troubleshooting.md