Librarian
A knowledge management MCP server for AI coding assistants. Capture insights, search with semantic understanding, and access a library of developer knowledge.
Installation
Claude Code (Recommended)
Plugin (full experience)
Includes MCP tools, slash commands, and hooks.
/plugin marketplace add telvokdev/librarian
/plugin install librarian@librarian
MCP only
claude mcp add librarian -- npx @telvok/librarian-mcp
Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Any MCP Client
Add to your MCP config:
{
"mcpServers": {
"librarian": {
"command": "npx",
"args": ["@telvok/librarian-mcp"]
}
}
}
Or install globally:
npm install -g @telvok/librarian-mcp
Quick Start
// Search before making decisions
brief({ query: "stripe webhook handling" })
// Capture what you learned
record({
insight: "Stripe retries webhooks but doesn't dedupe - always check idempotency key",
context: "payments, webhooks"
})
// Mark helpful entries to boost their ranking
mark_hit({ path: "local/stripe-webhooks-need-idempotency.md" })
// Browse the library
library_search({ query: "react patterns" })
API Reference (Beta)
Local Knowledge
| Tool | Purpose |
|---|
brief(query?, limit?) | Semantic search across your library |
record(insight, ...) | Capture knowledge worth keeping |
adopt(path, title?) | Copy imported entry to local library |
mark_hit(path) | Mark an entry as helpful (increases ranking) |
import_memories(format, path) | Import from other AI tools |
rebuild_index(force?) | Rebuild semantic search embeddings |
delete(path?, query?, confirm?) | Delete entries from local library |
Library
Browse and publish books at telvok.com. Free and paid content supported.
| Tool | Purpose |
|---|
library_search(query, filters?) | Search Telvok library |
library_download(slug) | Download a free book locally |
library_publish(name, attestation, ...) | Publish entries as a book |
my_books(filter?) | View published and downloaded books |
sync(slug?, force?) | Check for updates to owned books |
rate_book(slug, rating, ...) | Rate a book (1-5 stars) |
seller_analytics() | View download stats for your books |
Bounties
| Tool | Purpose |
|---|
bounty_create(title, ...) | Post a knowledge request |
bounty_list(query?, tags?, status?) | Browse available bounties |
bounty_claim(bounty_id) | Claim a bounty to fulfill |
bounty_submit(bounty_id, book_slug) | Submit fulfillment |
my_bounties(role?) | View your bounties |
Account
| Tool | Purpose |
|---|
auth(action) | Login, logout, status, complete |
help(topic?) | Get help on any tool |
feedback(message, type?) | Send feedback |
How Search Works
Librarian uses local AI embeddings for semantic search:
You saved: "Stripe webhooks need idempotency checks"
You search: "handling duplicate payment events"
→ It finds it.
all-MiniLM-L6-v2 model (384-dim embeddings)- ~30MB download on first run, cached locally
- No API calls — fully offline
Results ranked by semantic similarity, recency (60%), and hit count (40%).
Import Formats
| Format | Sources |
|---|
jsonl | Anthropic MCP Memory, mcp-knowledge-graph |
markdown | Obsidian, Basic Memory MCP |
cursor | Cursor Memory Bank |
json | Simple memory servers |
sqlite | mcp-memory-service, SQLite-vec |
Authentication
auth({ action: "login" }) — returns code + URL- Visit
telvok.com/device, enter the code
auth({ action: "complete" }) — saves API key locally
Keys stored in .librarian/.auth, expire after 90 days.
Library Structure
.librarian/
├── local/ # Your entries
├── imported/ # Downloaded books
├── packages/ # Purchased content
├── archived/ # Stale but searchable
├── index.json # Semantic embeddings
├── models/ # Cached embedding model
└── .auth # API key (git-ignored)
Contributing