Are you the author? Sign in to claim
Standalone Node MCP server: semantic search + knowledge graph + vault editing for Obsidian, no plugin required
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 — unlocksactive_note,dataview_query,base_query)
Contents — Why · Quick start · What you get · How it works · Companion plugin · Troubleshooting · Recent releases
.md files directly from disk. Obsidian can be closed; your vault is just a folder.qwen3-embedding:0.6b, nomic-embed-text, bge-m3, etc. with one env var.npx install — no clone, no build, no API key, no hosted endpoint. Vault content never leaves your machine./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.
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
18 MCP tools grouped by intent:
search, list_notes, read_notefind_connections, find_path_between, detect_themes, rank_notescreate_note, edit_note, apply_edit_preview, link_notes, move_note, delete_noteactive_note, dataview_query, base_queryreindex, index_status→ Arguments, examples, and response shapes: Tool reference
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)
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
Four most common:
~/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.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
ollama pull + docs/test polish→ Full changelog: docs/CHANGELOG.md · Forward plan: docs/roadmap.md · Build from source: docs/development.md
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).
apple-notes-brain — sibling
MCP server for Apple Notes on macOS: read, write, and search with full
Markdown round-trip in both directions.Apache License 2.0 — Copyright 2026 sweir1.
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases
@github✓ OfficialOfficial GitHub integration for repos, issues, PRs, and CI/CD workflows