librarian

View on GitHub

Knowledge capture for Claude Code and MCP clients

2 stars TypeScriptOthers Updated Feb 1, 2026

Documentation

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.

code

/plugin marketplace add telvokdev/librarian
/plugin install librarian@librarian

MCP only

bash

claude mcp add librarian -- npx @telvok/librarian-mcp

Cursor

Add to `.cursor/mcp.json`:

json

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

json

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Any MCP Client

Add to your MCP config:

json

{
  "mcpServers": {
    "librarian": {
      "command": "npx",
      "args": ["@telvok/librarian-mcp"]
    }
  }
}

Or install globally:

bash

npm install -g @telvok/librarian-mcp

Quick Start

javascript

// 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:

code

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

1. `auth({ action: "login" })` — returns code + URL

2. Visit `telvok.com/device`, enter the code

3. `auth({ action: "complete" })` — saves API key locally

Keys stored in `.librarian/.auth`, expire after 90 days.

Library Structure

code

.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

1. Fork the repository

2. Create a feature branch (`git checkout -b feature/my-feature`)

3. Commit changes (`git commit -m 'Add my feature'`)

4. Push (`git push origin feature/my-feature`)

5. Open a Pull Request

License

MIT - Telvok

Frequently asked questions

What is librarian?

librarian is Knowledge capture for Claude Code and MCP clients

How do I install librarian?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is librarian open source?

Yes — it is hosted on GitHub at https://github.com/telvokdev/librarian and has 2 stars.

Related MCP tools

servers

Model Context Protocol Servers

90,051 TypeScript

UI-TARS-desktop

The Open-Source Multimodal AI Agent Stack: Connecting Cutting-Edge AI Models and Agent Infra

38,840 TypeScript

agentvlmvision+11

n8n-mcp

A MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you

22,825 TypeScript

mcpmcp-servern8n+1

Figma-Context-MCP

MCP server to provide Figma layout information to AI coding agents like Cursor

15,766 TypeScript

aicursorfigma+2

inbox-zero

The world's best AI personal assistant for email. Open source app to help you reach inbox zero fast.

12,148 TypeScript

aiemailnextjs+14

instant

Instant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.

10,507 TypeScript

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP