Librarian

Give Claude a librarian for your markdown vault.

Librarian is the Karpathy LLM Wiki pattern, productionized as an MCP server — bidirectional graph traversal, auto-wikilinks, trigram search, community detection, and a D3 graph view, all from inside Claude. Works against any Obsidian vault or plain folder of markdown files.

Runs entirely locally. Your vault data never leaves your machine. Librarian reads and writes files on disk and communicates with Claude over stdio. No network calls, no telemetry, no cloud storage.

Quick Start

# 1. Install
brew install ngmeyer/tap/librarian-mcp

# 2. Point at your vault and auto-configure Claude
librarian-mcp --setup ~/my-vault

# 3. Restart Claude, then try:
#    /librarian analyze     — see your vault's knowledge graph
#    /librarian search      — find anything across all notes
#    /librarian status      — vault health overview

--setup writes the MCP server config into Claude Desktop and Claude Code (with backups), and installs the /librarian skill so you get 12 slash commands out of the box.

Install

Homebrew (macOS)

brew install ngmeyer/tap/librarian-mcp

Pre-built binaries

Download from GitHub Releases for macOS (arm64/x86_64), Linux (arm64/x86_64), and Windows. Place the binary on your PATH.

Build from source (requires Rust)

cargo install --git https://github.com/ngmeyer/librarian-mcp

How It Works

Librarian is a standalone binary — it works directly on your markdown files. Obsidian does not need to be running (and they can run simultaneously without conflict). Claude connects via the Model Context Protocol over stdio.

How is this different from...

	Read files directly	Obsidian Copilot	mcp-obsidian	Librarian
Trigram-indexed search	No	Plugin	Plugin	Yes
Auto-wikilinks on write	No	No	No	Yes
Knowledge graph traversal	No	No	Partial	Yes (BFS, shortest path)
Community detection	No	No	No	Yes (Louvain)
Interactive graph viz	No	No	No	Yes (D3.js)
Works without Obsidian	Yes	No	No	Yes
Works in Claude Code	Yes (manual)	No	No	Yes
Standalone binary	N/A	No	No	Yes

Setup

librarian-mcp --setup ~/my-vault

This auto-configures Claude Desktop and Claude Code (with backups of existing configs). Restart Claude to connect.

Multiple vaults

librarian-mcp --setup ~/vaults/notes ~/vaults/research

Manual configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json) or Claude Code config (~/.claude/settings.json):

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

Environment variables

LIBRARIAN_VAULT=/path/to/vault        # Single vault
LIBRARIAN_VAULTS=/vault/one:/vault/two # Multiple vaults (colon-separated, Unix only)

Tools

Librarian exposes 17 tools to Claude:

Tool	Description
library_search	Full-text search across all vault files (trigram-indexed)
library_read	Read a file by relative path
library_write	Write a file with auto-wikilink detection
library_list	List files and directories (shows vault roots when multi-vault)
library_links	Get backlinks and outgoing wikilinks for a file
library_tags	List all #tags with counts, optionally filtered by prefix
library_metadata	Read YAML frontmatter from a file
library_daily	Create or append to a daily note (Journal/YYYY/YYYY-MM-DD.md)
library_stats	Vault statistics: file count, word count, link density, orphan notes
library_suggest_links	Find unlinked mentions of existing notes (including aliases)
library_traverse	BFS traversal from a note — explore the topic neighborhood N hops deep
library_shortest_path	Find the shortest link chain between two notes
library_graph_analysis	Connected components, hub notes, bridges, orphans
library_import	Convert PDF, DOCX, images, etc. to markdown (requires MarkItDown)
library_cluster	Detect topic communities using Louvain modularity optimization
library_visualize	Generate interactive HTML graph visualization (D3.js)
library_report	Comprehensive vault analysis: god nodes, communities, bridges

The /librarian Skill

--setup installs a Claude Code skill that gives you 12 high-level commands built on the tools above:

Command	What it does
/librarian search <query>	Deep search with synthesis across top results
/librarian analyze	Full vault analysis — communities, hubs, visualization
/librarian graph [note]	Explore a note's neighborhood or vault-wide structure
/librarian connect [path]	Find and apply missing wikilinks
/librarian daily [text]	Append to today's daily note
/librarian status	Quick vault health check
/librarian ingest [path]	Import a local markdown file into the vault
/librarian import <file>	Convert PDF/DOCX/images to vault markdown
/librarian from web <url>	Import a web page as a vault note
/librarian from twitter <url>	Import an X/Twitter thread
/librarian from gmail <query>	Import Gmail threads
/librarian from calendar	Import calendar events

Example: Research Skill Graph

The repo includes a 16-file example vault demonstrating multi-lens research analysis — 6 analytical lenses that force different perspectives on any topic.

To try it after cloning:

git clone https://github.com/ngmeyer/librarian-mcp
cd librarian-mcp
librarian-mcp --setup examples/research-skill-graph

Then in Claude Code: "Follow the execution instructions in index.md. Research: Why are prediction market edges compressing?"

The vault includes source evaluation (5-tier trust system), contradiction protocol, synthesis rules, and a knowledge layer that compounds across projects. See examples/research-skill-graph/index.md for the full system.

Features

Auto-linking

When Claude writes files via library_write, Librarian scans for mentions of existing note titles and wraps them in [[wikilinks]]. This happens only on explicit writes — Librarian never modifies files you didn't ask it to write.

Links use canonical file names so they resolve correctly in Obsidian's graph view, even on case-sensitive filesystems. Frontmatter aliases are supported: if a note has aliases: [ML, machine learning], mentions will auto-link using [[Note Name|ML]] format.

Auto-linking skips code blocks, inline code, URLs, and existing wikilinks to avoid corrupting content.

Knowledge graph traversal

Librarian builds a bidirectional graph from your vault's [[wikilinks]] and exposes three graph tools:

• Traverse — BFS from any note, N hops deep. "Show me everything connected to this topic."
• Shortest path — Find the link chain between two notes. "How are these ideas connected?"
• Graph analysis — Connected components, hub notes, bridge notes, orphans. "What's the structure of my vault?"

Community detection

Louvain modularity optimization identifies topic clusters in your vault. Combined with betweenness centrality and PageRank, the report tool ranks "god nodes" (structurally important notes) and finds surprising cross-community connections.

Search

Search is backed by an in-memory trigram index built on startup. Handles vaults with 10,000+ files.

Exclusion patterns

By default, Librarian skips .obsidian/, .trash/, .git/, and node_modules/. Drop a .librarianignore file (gitignore syntax) in your vault root to customize:

# .librarianignore
templates/
private/

Obsidian compatibility

Librarian works seamlessly alongside Obsidian — both can be open at the same time:

• Reads and writes standard [[wikilinks]] and [[note|display text]]
• Respects YAML frontmatter and aliases
• Skips .obsidian/ and .trash/ directories
• Auto-linked wikilinks resolve in Obsidian's graph view
• Daily notes follow Journal/YYYY/YYYY-MM-DD.md convention

License

MIT