Labsco
sweir1 logo

obsidian-brain

★ 8

from sweir1

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.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#analytics#database#git#maps#security#memory

obsidian-brain

npm version License: Apache 2.0 Node ≥ 20 GitHub stars

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.

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

Copy & paste — that's it
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

Recent releases

<!-- GENERATED:recent-releases — auto-pulled from docs/CHANGELOG.md by scripts/gen-readme-recent.mjs. Edit CHANGELOG.md, then run `npm run gen-readme-recent`. -->
  • 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
<!-- /GENERATED:recent-releases -->

→ 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.

License

Apache License 2.0 — Copyright 2026 sweir1.