obsidian-brain
About
Standalone Obsidian MCP server with semantic search, knowledge graph analytics (PageRank, Louvain, shortest path), and vault editing — no plugin, no REST API, works when Obsidian is closed.
Details
- Author
- sweir1
- Categories
- Productivity, Other, Knowledge Base, Search
Jump to
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/binsymlinks that Claude Desktop needs, merges obsidian-brain into yourclaude_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:](#recent-releases)scripts/install.sh.
Requires Node 20+ and an Obsidian vault (or any folder of.mdfiles — Obsidian itself is optional).
Wire obsidian-brain into your MCP client. Example forClaude 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?ThemacOS walkthroughcovers 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): seeInstall in your MCP client.
→ Full env-var reference:Configuration→ Model / preset / Ollama details:Embedding model→ Migrating from aaronsb's plugin:Migration guide
- 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(requirescompanion plugin) —active_note,dataview_query,base_query
- Maintenance—reindex,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), andsearch's defaulthybridmode 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)
Ship plugin and server at thesame 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
- "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_VERSIONmismatch—better-sqlite3built against a different Node ABI. Fix:PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
- Vault path not configured—VAULT_PATHis unset. Set it in theenvblock of your client config or shell.
- Old version loading vianpx(your client still shows the previous release after a publish) — stale npx cache. Fix:rm -rf ~/.npm/_npx, then restart your client. Keeping@latestin your config prevents this.
→ Full troubleshooting guide (watcher not firing, stale index, running multiple clients, timeouts, embedding-dim mismatch, log locations):docs/troubleshooting.md
- 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 + autoollama 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
Thanks toobra/knowledge-graphandaaronsb/obsidian-mcp-pluginfor the ideas and code this project draws on. AlsoXenova/transformers.js(local embeddings),graphology(graph analytics), andsqlite-vec(vector search in SQLite).
Apache License 2.0— Copyright 2026 sweir1.
MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.
A server for the Scrapbox/CoSense platform to retrieve, list, search, and create pages.
Markdown and Obsidian compatible knowledge graph.
An MCP server for interacting with the YuQue knowledge base, enabling AI assistants to perform operations on documents and information.
NVIDIA AI Developer Stack as Compressed Knowledge Graph (CKG) - 20 domains, 998 notes, agents traverse typed dependency edges instead of scanning docs.
Multi-device file sync, dev-doc CRUD, task management, and session handoffs for AI agents - MCP + OpenAPI dual surface.
Access and manage your library on Apple Books.
Interact with Apple Notes using natural language on macOS.
A server for interacting with the Bear note-taking application.
Provides direct access to your Bear notes database for comprehensive note management, bypassing standard API limitations.
Standalone Obsidian MCP server with semantic search, knowledge graph analytics (PageRank, Louvain, shortest path), and vault editing — no plugin, no REST API, works when Obsidian is closed.
A standalone Node MCP server that gives Claude (and any other MCP client)semantic search + knowledge graph + vault editingover 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-brainCompanion 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
- Works without Obsidian running— unlike Local REST API-based servers, obsidian-brain reads.mdfiles 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 toqwen3-embedding:0.6b,nomic-embed-text,bge-m3, etc. with one env var.
- All in onenpxinstall— no clone, no build, no API key, no hosted endpoint. Vault content never leaves your machine.
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/binsymlinks that Claude Desktop needs, merges obsidian-brain into yourclaude_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.mdfiles — Obsidian itself is optional).
Wire obsidian-brain into your MCP client. Example forClaude 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?ThemacOS walkthroughcovers 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): seeInstall in your MCP client.
→ Full env-var reference:Configuration→ Model / preset / Ollama details:Embedding model→ Migrating from aaronsb's plugin:Migration guide
- 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(requirescompanion plugin) —active_note,dataview_query,base_query
- Maintenance—reindex,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), andsearch's defaulthybridmode 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)
Ship plugin and server at thesame 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
- "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_VERSIONmismatch—better-sqlite3built against a different Node ABI. Fix:PATH=/opt/homebrew/bin:$PATH npm rebuild -g better-sqlite3.
- Vault path not configured—VAULT_PATHis unset. Set it in theenvblock of your client config or shell.
- Old version loading vianpx(your client still shows the previous release after a publish) — stale npx cache. Fix:rm -rf ~/.npm/_npx, then restart your client. Keeping@latestin your config prevents this.
→ Full troubleshooting guide (watcher not firing, stale index, running multiple clients, timeouts, embedding-dim mismatch, log locations):docs/troubleshooting.md
- 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 + autoollama 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
Thanks toobra/knowledge-graphandaaronsb/obsidian-mcp-pluginfor the ideas and code this project draws on. AlsoXenova/transformers.js(local embeddings),graphology(graph analytics), andsqlite-vec(vector search in SQLite).
Apache License 2.0— Copyright 2026 sweir1.
MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.
A server for the Scrapbox/CoSense platform to retrieve, list, search, and create pages.
Markdown and Obsidian compatible knowledge graph.
An MCP server for interacting with the YuQue knowledge base, enabling AI assistants to perform operations on documents and information.
NVIDIA AI Developer Stack as Compressed Knowledge Graph (CKG) - 20 domains, 998 notes, agents traverse typed dependency edges instead of scanning docs.
Multi-device file sync, dev-doc CRUD, task management, and session handoffs for AI agents - MCP + OpenAPI dual surface.
Access and manage your library on Apple Books.
Interact with Apple Notes using natural language on macOS.
A server for interacting with the Bear note-taking application.
Provides direct access to your Bear notes database for comprehensive note management, bypassing standard API limitations.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
