calibre-librarian¶

Local-first RAG librarian for Calibre e-book libraries.

Index a scoped subset of your Calibre library, search it semantically, and expose the results to coding agents through MCP tools — with citations and local file paths.

Requirements¶

• Python 3.11+
• Calibre (calibredb and ebook-convert on PATH)
• Ollama with nomic-embed-text for embeddings
• EPUB or PDF books in your Calibre library

Install¶

cd library
uv sync

Configure¶

Your settings live in the private data root, <data_root>/config/library.toml under [general] (default data root ~/tool-chest-data). Edit them in the workbench (Settings → Books) or with library config set (JSON on stdin). The old ~/.config/library/config.toml is no longer read; make config-migrate (from the repository root) moves it. The keys are:

[general]
calibre_library = "~/Calibre Library"
db = "~/.local/share/library/index.db"
embedding_model = "nomic-embed-text"
ollama_base_url = "http://localhost:11434"

# Scope: only index books matching this query
include_tags = ["agent-reference"]
exclude_tags = ["Fantasy", "Fiction"]

# Or use a full Calibre search expression:
# include_query = 'tags:"=agent-reference" and (formats:epub or formats:pdf)'

Tag books in Calibre (e.g. agent-reference) or create a virtual library and reference it with include_query = 'vl:"Technical Reference"'.

Usage¶

# Show which books match your scope
uv run library show-scope

# Index in-scope books (chunk + embed)
# By default this first converts any PDF-only books to EPUB via Calibre
# and attaches the result to the same record, since EPUB extracts more
# cleanly for chunking/search. Skip that step with --no-convert.
uv run library index

# Convert PDF-only in-scope books to EPUB on demand, without indexing
uv run library convert

# Preview without writing
uv run library index --dry-run

# Search from the CLI
uv run library search "threat modeling for APIs" --limit 5

# Start the MCP server for Cursor / Claude Code
uv run library serve

MCP tools¶

Integrations¶

See INTEGRATION.md for the event hook surface (search, passage, indexed). PKM adapters live in the consumer repo, not in this package.

Privacy¶

• All indexing, embedding, and search runs locally.
• Embeddings use Ollama on localhost by default.
• Calibre metadata is read via calibredb subprocess only.

Development¶

make test