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 bge-m3, nomic-embed-text, qwen3-embedding-8b, 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

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.

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

17 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

→ 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 · W

... [View full README on GitHub](https://github.com/sweir1/obsidian-brain#readme)