{"id":51551315,"url":"https://github.com/ngmeyer/librarian-mcp","last_synced_at":"2026-07-12T14:01:14.222Z","repository":{"id":353994371,"uuid":"1207982009","full_name":"ngmeyer/librarian-mcp","owner":"ngmeyer","description":"The Karpathy LLM Wiki pattern, productionized. MCP server that gives Claude a librarian for your Obsidian vault — graph traversal, auto-wikilinks, trigram search.","archived":false,"fork":false,"pushed_at":"2026-04-26T15:44:35.000Z","size":100,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T17:25:19.272Z","etag":null,"topics":["claude","claude-code","karpathy","knowledge-graph","knowledge-management","llm-wiki","markdown","mcp","mcp-server","obsidian","rust","wiki"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ngmeyer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-11T16:57:10.000Z","updated_at":"2026-04-26T15:44:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ngmeyer/librarian-mcp","commit_stats":null,"previous_names":["ngmeyer/librarian-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ngmeyer/librarian-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngmeyer%2Flibrarian-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngmeyer%2Flibrarian-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngmeyer%2Flibrarian-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngmeyer%2Flibrarian-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ngmeyer","download_url":"https://codeload.github.com/ngmeyer/librarian-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ngmeyer%2Flibrarian-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35393398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","karpathy","knowledge-graph","knowledge-management","llm-wiki","markdown","mcp","mcp-server","obsidian","rust","wiki"],"created_at":"2026-07-10T00:00:52.211Z","updated_at":"2026-07-12T14:01:14.214Z","avatar_url":"https://github.com/ngmeyer.png","language":"Rust","funding_links":[],"categories":["Documentation, Knowledge \u0026 Learning"],"sub_categories":[],"readme":"# Librarian\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-Skill-blueviolet?logo=anthropic)](https://claude.ai/code)\n[![MCP](https://img.shields.io/badge/MCP-Server-orange?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJ3aGl0ZSI+PHBhdGggZD0iTTEyIDJMMyA3djEwbDkgNSA5LTV2LTEweiIvPjwvc3ZnPg==)](https://modelcontextprotocol.io)\n[![Homebrew](https://img.shields.io/badge/Homebrew-Available-FBB040?logo=homebrew\u0026logoColor=white)](https://github.com/ngmeyer/homebrew-tap)\n[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)]()\n\nGive Claude a librarian for your markdown vault.\n\nLibrarian 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.\n\n\u003e **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.\n\n## Quick Start\n\n```bash\n# 1. Install\nbrew install ngmeyer/tap/librarian-mcp\n\n# 2. Point at your vault and auto-configure Claude\nlibrarian-mcp --setup ~/my-vault\n\n# 3. Restart Claude, then try:\n#    /librarian analyze     — see your vault's knowledge graph\n#    /librarian search      — find anything across all notes\n#    /librarian status      — vault health overview\n```\n\n`--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.\n\n## Install\n\n### Homebrew (macOS)\n\n```bash\nbrew install ngmeyer/tap/librarian-mcp\n```\n\n### Pre-built binaries\n\nDownload 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.\n\n### Build from source (requires Rust)\n\n```bash\ncargo install --git https://github.com/ngmeyer/librarian-mcp\n```\n\n## How It Works\n\nLibrarian 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.\n\n### How is this different from...\n\n| | Read files directly | Obsidian Copilot | mcp-obsidian | **Librarian** |\n|---|---|---|---|---|\n| Trigram-indexed search | No | Plugin | Plugin | **Yes** |\n| Auto-wikilinks on write | No | No | No | **Yes** |\n| Knowledge graph traversal | No | No | Partial | **Yes (BFS, shortest path)** |\n| Community detection | No | No | No | **Yes (Louvain)** |\n| Interactive graph viz | No | No | No | **Yes (D3.js)** |\n| Works without Obsidian | Yes | No | No | **Yes** |\n| Works in Claude Code | Yes (manual) | No | No | **Yes** |\n| Standalone binary | N/A | No | No | **Yes** |\n\n## Setup\n\n```bash\nlibrarian-mcp --setup ~/my-vault\n```\n\nThis auto-configures Claude Desktop and Claude Code (with backups of existing configs). Restart Claude to connect.\n\n### Multiple vaults\n\n```bash\nlibrarian-mcp --setup ~/vaults/notes ~/vaults/research\n```\n\n### Manual configuration\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`) or Claude Code config (`~/.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"librarian\": {\n      \"command\": \"librarian-mcp\",\n      \"args\": [\"/path/to/your/vault\"]\n    }\n  }\n}\n```\n\n### Environment variables\n\n```bash\nLIBRARIAN_VAULT=/path/to/vault        # Single vault\nLIBRARIAN_VAULTS=/vault/one:/vault/two # Multiple vaults (colon-separated, Unix only)\n```\n\n## Tools\n\nLibrarian exposes 17 tools to Claude:\n\n| Tool | Description |\n|------|-------------|\n| `library_search` | Full-text search across all vault files (trigram-indexed) |\n| `library_read` | Read a file by relative path |\n| `library_write` | Write a file with auto-wikilink detection |\n| `library_list` | List files and directories (shows vault roots when multi-vault) |\n| `library_links` | Get backlinks and outgoing wikilinks for a file |\n| `library_tags` | List all #tags with counts, optionally filtered by prefix |\n| `library_metadata` | Read YAML frontmatter from a file |\n| `library_daily` | Create or append to a daily note (Journal/YYYY/YYYY-MM-DD.md) |\n| `library_stats` | Vault statistics: file count, word count, link density, orphan notes |\n| `library_suggest_links` | Find unlinked mentions of existing notes (including aliases) |\n| `library_traverse` | BFS traversal from a note — explore the topic neighborhood N hops deep |\n| `library_shortest_path` | Find the shortest link chain between two notes |\n| `library_graph_analysis` | Connected components, hub notes, bridges, orphans |\n| `library_import` | Convert PDF, DOCX, images, etc. to markdown (requires [MarkItDown](https://github.com/microsoft/markitdown)) |\n| `library_cluster` | Detect topic communities using Louvain modularity optimization |\n| `library_visualize` | Generate interactive HTML graph visualization (D3.js) |\n| `library_report` | Comprehensive vault analysis: god nodes, communities, bridges |\n\n## The /librarian Skill\n\n`--setup` installs a Claude Code skill that gives you 12 high-level commands built on the tools above:\n\n| Command | What it does |\n|---------|-------------|\n| `/librarian search \u003cquery\u003e` | Deep search with synthesis across top results |\n| `/librarian analyze` | Full vault analysis — communities, hubs, visualization |\n| `/librarian graph [note]` | Explore a note's neighborhood or vault-wide structure |\n| `/librarian connect [path]` | Find and apply missing wikilinks |\n| `/librarian daily [text]` | Append to today's daily note |\n| `/librarian status` | Quick vault health check |\n| `/librarian ingest [path]` | Import a local markdown file into the vault |\n| `/librarian import \u003cfile\u003e` | Convert PDF/DOCX/images to vault markdown |\n| `/librarian from web \u003curl\u003e` | Import a web page as a vault note |\n| `/librarian from twitter \u003curl\u003e` | Import an X/Twitter thread |\n| `/librarian from gmail \u003cquery\u003e` | Import Gmail threads |\n| `/librarian from calendar` | Import calendar events |\n\n## Example: Research Skill Graph\n\nThe repo includes a 16-file example vault demonstrating multi-lens research analysis — 6 analytical lenses that force different perspectives on any topic.\n\nTo try it after cloning:\n\n```bash\ngit clone https://github.com/ngmeyer/librarian-mcp\ncd librarian-mcp\nlibrarian-mcp --setup examples/research-skill-graph\n```\n\nThen in Claude Code: \"Follow the execution instructions in index.md. Research: Why are prediction market edges compressing?\"\n\nThe 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.\n\n## Features\n\n### Auto-linking\n\nWhen 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.\n\nLinks 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.\n\nAuto-linking skips code blocks, inline code, URLs, and existing wikilinks to avoid corrupting content.\n\n### Knowledge graph traversal\n\nLibrarian builds a bidirectional graph from your vault's `[[wikilinks]]` and exposes three graph tools:\n\n- **Traverse** — BFS from any note, N hops deep. \"Show me everything connected to this topic.\"\n- **Shortest path** — Find the link chain between two notes. \"How are these ideas connected?\"\n- **Graph analysis** — Connected components, hub notes, bridge notes, orphans. \"What's the structure of my vault?\"\n\n### Community detection\n\nLouvain 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.\n\n### Search\n\nSearch is backed by an in-memory trigram index built on startup. Handles vaults with 10,000+ files.\n\n### Exclusion patterns\n\nBy default, Librarian skips `.obsidian/`, `.trash/`, `.git/`, and `node_modules/`. Drop a `.librarianignore` file (gitignore syntax) in your vault root to customize:\n\n```gitignore\n# .librarianignore\ntemplates/\nprivate/\n```\n\n## Obsidian compatibility\n\nLibrarian works seamlessly alongside Obsidian — both can be open at the same time:\n\n- Reads and writes standard `[[wikilinks]]` and `[[note|display text]]`\n- Respects YAML frontmatter and `aliases`\n- Skips `.obsidian/` and `.trash/` directories\n- Auto-linked wikilinks resolve in Obsidian's graph view\n- Daily notes follow `Journal/YYYY/YYYY-MM-DD.md` convention\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngmeyer%2Flibrarian-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fngmeyer%2Flibrarian-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fngmeyer%2Flibrarian-mcp/lists"}