book-archivar

Give an MCP-capable AI agent (Claude Desktop, Claude Code, your own agent) access to your own EPUB library, fully local:

• list_books – what is in the archive

• search_books – semantic search over all books (or one)

• list_chapters – a book's table of contents

• get_chapter – the exact text of one chapter, by title or index

Unlike plain chunk-search tools, the agent can navigate by chapter and read a whole chapter verbatim.

This is the basic edition: pure Python, no Rust, no daemon. Anything beyond that (inbox watcher, fuzzy duplicate review, ...) is meant to live in add-ons.

Requirements

• Python 3.12+

• An OpenAI-compatible embeddings endpoint. The default is Ollama: ollama pull bge-m3

Related MCP server: mcp-ebook-server

Install

git clone <this repo> && cd book-archivar
python3 -m venv venv
./venv/bin/pip install -e .

Use

# 1. import books (files or folders; originals are never touched or deleted)
./venv/bin/book-archivar import ~/Books

# 2. run the MCP server (stdio)
./venv/bin/book-archivar serve

Claude Desktop (claude_desktop_config.json) / Claude Code (claude mcp add):

{
  "mcpServers": {
    "books": { "command": "/path/to/venv/bin/book-archivar", "args": ["serve"] }
  }
}

For a network service use serve --transport streamable-http --host 127.0.0.1 --port 8000.

Configuration

Everything has a default; see config.example.yaml. Pass --config FILE, set BOOK_ARCHIVAR_CONFIG, or place a config.yaml in the working directory. Data lives in ~/.local/share/book-archivar (library/<slug>/{book.md,chapters.json,metadata.json} plus chroma/).

Changing the embedding model requires re-importing (delete the data dir): vectors from different models are not comparable.

How it works

EPUB → Markdown (EbookLib + a small HTML converter) → chapter byte ranges from the EPUB table of contents (anchors inside a file are honoured; without a TOC each document becomes a chapter) → fixed-size overlapping chunks per chapter → embeddings → Chroma. Importing the same file twice is detected by SHA-256.

Limitations

• EPUB only (no PDF/MOBI).

• The Markdown conversion is deliberately simple: tables, footnotes and images are reduced to text.

• Chapter quality depends on the EPUB's TOC.

• Only use it with books you are allowed to use; do not publish the generated library.

Tests

./venv/bin/pip install -e ".[dev]" && ./venv/bin/pytest

Dual-licensed under MIT or Apache-2.0, at your option.