https://github.com/ngmeyer/librarian-mcp
The Karpathy LLM Wiki pattern, productionized. MCP server that gives Claude a librarian for your Obsidian vault — graph traversal, auto-wikilinks, trigram search.
https://github.com/ngmeyer/librarian-mcp
claude claude-code karpathy knowledge-graph knowledge-management llm-wiki markdown mcp mcp-server obsidian rust wiki
Last synced: 7 days ago
JSON representation
The Karpathy LLM Wiki pattern, productionized. MCP server that gives Claude a librarian for your Obsidian vault — graph traversal, auto-wikilinks, trigram search.
- Host: GitHub
- URL: https://github.com/ngmeyer/librarian-mcp
- Owner: ngmeyer
- License: mit
- Created: 2026-04-11T16:57:10.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T15:44:35.000Z (3 months ago)
- Last Synced: 2026-04-26T17:25:19.272Z (3 months ago)
- Topics: claude, claude-code, karpathy, knowledge-graph, knowledge-management, llm-wiki, markdown, mcp, mcp-server, obsidian, rust, wiki
- Language: Rust
- Size: 97.7 KB
- Stars: 6
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-claude-code - Librarian - A standalone MCP server that gives Claude a markdown second-brain over any Obsidian vault or folder of `.md` files, with trigram search, auto-wikilinks on write, and real graph analytics (Louvain communities, PageRank, shortest-path, D3 visualization). Runs entirely locally with no network calls or telemetry, productionizing the "LLM wiki" pattern. (Documentation, Knowledge & Learning)
README
# Librarian
[](LICENSE)
[](https://claude.ai/code)
[](https://modelcontextprotocol.io)
[](https://github.com/ngmeyer/homebrew-tap)
[]()
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](https://obsidian.md) 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
```bash
# 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)
```bash
brew install ngmeyer/tap/librarian-mcp
```
### Pre-built binaries
Download from [GitHub Releases](https://github.com/ngmeyer/librarian-mcp/releases) for macOS (arm64/x86_64), Linux (arm64/x86_64), and Windows. Place the binary on your PATH.
### Build from source (requires Rust)
```bash
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](https://modelcontextprotocol.io) 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
```bash
librarian-mcp --setup ~/my-vault
```
This auto-configures Claude Desktop and Claude Code (with backups of existing configs). Restart Claude to connect.
### Multiple vaults
```bash
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`):
```json
{
"mcpServers": {
"librarian": {
"command": "librarian-mcp",
"args": ["/path/to/your/vault"]
}
}
}
```
### Environment variables
```bash
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](https://github.com/microsoft/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 ` | 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 ` | Convert PDF/DOCX/images to vault markdown |
| `/librarian from web ` | Import a web page as a vault note |
| `/librarian from twitter ` | Import an X/Twitter thread |
| `/librarian from gmail ` | 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:
```bash
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`](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:
```gitignore
# .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