Librarian MCP Server

A local MCP server that gives AI agents structured access to a personal Obsidian knowledge vault. Notes remain portable Markdown, while Librarian enforces organization, provenance, deduplication, and git-backed history.

What it does

• Stores OKF-compatible Markdown notes in a flat Obsidian vault.
• Organizes concepts through Maps of Content (MOCs).
• Combines local semantic search with lexical matching and exact filters.
• Rejects duplicate concepts, invalid notes, and edits to immutable source notes.
• Commits every mutation to the vault's git history.
• Reports broken links, orphaned notes, malformed frontmatter, and WikiLinks.

All search and storage are local. The first semantic search downloads the BAAI/bge-small-en-v1.5 model (about 130 MB); later searches run offline.

Install

Requires Python 3.11+.

pip install .

Or with uv:

uv sync

Run

librarian --vault /path/to/vault

You can also set the vault path with LIBRARIAN_VAULT:

LIBRARIAN_VAULT=/path/to/vault librarian

On first run, Librarian creates the vault, initializes git, and adds a root MOC. Configure your MCP client to launch the server over stdio, for example:

{
  "mcpServers": {
    "librarian": {
      "command": "librarian",
      "args": ["--vault", "/path/to/vault"]
    }
  }
}

Tools

Tool	Purpose
get_vault_seed	Return a bounded overview of MOCs and recent notes
query_knowledge	Search notes semantically and lexically
read_concept	Read a complete note
create_concept	Create a validated note and wire it into an MOC
enrich_concept	Append content to a named section
lint_graph	Report graph and formatting problems

See spec.md for the full contracts and design decisions.

Development

uv sync --extra dev
uv run --extra dev pytest