How do I install Obsidian Brain?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Obsidian Brain need an API key?

The publisher lists these environment variables: VAULT_PATH, DATA_DIR, EMBEDDING_PRESET, EMBEDDING_MODEL, EMBEDDING_PROVIDER, OLLAMA_BASE_URL, OLLAMA_EMBEDDING_DIM, OLLAMA_NUM_CTX, OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL, OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL, OBSIDIAN_BRAIN_NO_WATCH, OBSIDIAN_BRAIN_NO_CATCHUP, OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS, OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS, OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS, OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS, OBSIDIAN_BRAIN_CONFIG_DIR, OBSIDIAN_BRAIN_DEBUG, OBSIDIAN_BRAIN_LOG_FORMAT.

What transport does Obsidian Brain use?

Obsidian Brain runs locally over stdio.

When was Obsidian Brain last checked?

Last checked 2026-10-27. Standalone Node MCP server: semantic search + knowledge graph + vault editing for Obsidian, no plugin required

Obsidian Brain MCP 服务器

1VAULT_PATH=<value> DATA_DIR=<value> EMBEDDING_PRESET=<value> EMBEDDING_MODEL=<value> EMBEDDING_PROVIDER=<value> OLLAMA_BASE_URL=<value> OLLAMA_EMBEDDING_DIM=<value> OLLAMA_NUM_CTX=<value> OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL=<value> OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL=<value> OBSIDIAN_BRAIN_NO_WATCH=<value> OBSIDIAN_BRAIN_NO_CATCHUP=<value> OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS=<value> OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS=<value> OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS=<value> OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS=<value> OBSIDIAN_BRAIN_CONFIG_DIR=<value> OBSIDIAN_BRAIN_DEBUG=<value> OBSIDIAN_BRAIN_LOG_FORMAT=<value> claude mcp add sweir1-obsidian-brain -- npx -y obsidian-brain@1.7.24

1{2 "mcpServers": {3 "sweir1-obsidian-brain": {4 "command": "npx",5 "args": [6 "-y",7 "[email protected]"8 ],9 "env": {10 "VAULT_PATH": "<value>",11 "DATA_DIR": "<value>",12 "EMBEDDING_PRESET": "<value>",13 "EMBEDDING_MODEL": "<value>",14 "EMBEDDING_PROVIDER": "<value>",15 "OLLAMA_BASE_URL": "<value>",16 "OLLAMA_EMBEDDING_DIM": "<value>",17 "OLLAMA_NUM_CTX": "<value>",18 "OBSIDIAN_BRAIN_OLLAMA_AUTO_PULL": "<value>",19 "OBSIDIAN_BRAIN_OLLAMA_BYOM_AUTO_PULL": "<value>",20 "OBSIDIAN_BRAIN_NO_WATCH": "<value>",21 "OBSIDIAN_BRAIN_NO_CATCHUP": "<value>",22 "OBSIDIAN_BRAIN_WATCH_DEBOUNCE_MS": "<value>",23 "OBSIDIAN_BRAIN_COMMUNITY_DEBOUNCE_MS": "<value>",24 "OBSIDIAN_BRAIN_TOOL_TIMEOUT_MS": "<value>",25 "OBSIDIAN_BRAIN_MAX_CHUNK_TOKENS": "<value>",26 "OBSIDIAN_BRAIN_CONFIG_DIR": "<value>",27 "OBSIDIAN_BRAIN_DEBUG": "<value>",28 "OBSIDIAN_BRAIN_LOG_FORMAT": "<value>"29 }30 }31 }32}

obsidian-brain

A standalone Node MCP server that gives Claude (and any other MCP client) semantic search + knowledge graph + vault editing 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.

📖 Full docs → sweir1.github.io/obsidian-brain Companion plugin → sweir1/obsidian-brain-plugin (optional — unlocks active_note, dataview_query, base_query)

Contents — Why · Quick start · What you get · How it works · Companion plugin · Troubleshooting · Recent releases

Why obsidian-brain?

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.

Quick start

One-line install (macOS + Claude Desktop)

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

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):

{
  "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.

[!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.

→ Full env-var reference: Configuration → Model / preset / Ollama details: Embedding model → Migrating from aaronsb's plugin: Migration guide

What you get

18 MCP tools grouped by intent:

Find & read — search, list_notes, read_note
Understand the graph — find_connections, find_path_between, detect_themes, rank_notes
Write — create_note, edit_note, apply_edit_preview, link_notes, move_note, delete_note
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.

→ Deeper write-up — why stdio, why SQLite, why local embeddings: Architecture → Live watcher behaviour + debounces: Live updates → Scheduled reindex (macOS launchd / Linux systemd): Scheduled indexing (macOS) · (Linux)

Companion plugin (optional)

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.

→ Security model, capability handshake, Dataview / Bases feature coverage: Companion plugin

Troubleshooting

Four most common:

"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

Recent releases

v1.7.24 (2026-05-16) — embeddings.md BYOM callout + 5 devDep bumps
v1.7.23 (2026-05-16) — BYOM Ollama auto-pull gate + logger sweep + SIGTERM unit test
v1.7.22 (2026-05-15) — structured stderr (NDJSON) + Ollama preparing-state + dependabot security bumps + SIGTERM drain integration test
v1.7.21 (2026-04-27) — install.sh vault-picker fix + auto ollama pull + docs/test polish
v1.7.20 (2026-04-27) — Ollama prefix-lookup bug + 13 audit polish items

→ Full changelog: docs/CHANGELOG.md · Forward plan: docs/roadmap.md · Build from source: docs/development.md

Credits

Thanks to obra/knowledge-graph and aaronsb/obsidian-mcp-plugin for the ideas and code this project draws on. Also Xenova/transformers.js (local embeddings), graphology (graph analytics), and sqlite-vec (vector search in SQLite).

Related projects

apple-notes-brain — sibling MCP server for Apple Notes on macOS: read, write, and search with full Markdown round-trip in both directions.

Obsidian Brain

添加此服务器

Tools

Questions

用我们的密钥与日志托管一份副本。

Server facts