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.

Related MCP server: obsidian-local-rest-api

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

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

Development

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