bookworm

BookWorm

A local MCP server that turns your ebook library into a searchable knowledge base. Drop books into a folder, run ingest, and Claude Code automatically searches relevant passages when it needs reference material.

Supports PDF, EPUB, MOBI, Markdown, plain text, and HTML. Runs entirely locally -- no external API required.

---

Getting Started

1. Install

git clone <repo-url> && cd BookWorm
python -m venv .venv && source .venv/bin/activate
pip install -e .

This installs the bookworm CLI and all dependencies (pymupdf, chromadb, sentence-transformers, etc). First run will download the embedding model (~80MB).

2. Add Your Books

Copy or symlink books into the inbox:

cp ~/Books/clean-code.epub books/inbox/
cp ~/Books/designing-data-intensive-apps.pdf books/inbox/

Supported formats: EPUB, PDF, MOBI, Markdown (.md), plain text (.txt), HTML (.html/.htm)

Duplicate formats: If you have the same book as clean-code.pdf, clean-code.epub, and clean-code.mobi, only add one to the inbox. Indexing the same book in multiple formats produces duplicate search results.

When choosing which format to keep, prefer in this order:

Priority	Format	Why
1st	EPUB	Cleanest text extraction, chapter boundaries from TOC, smallest files
2nd	PDF	Good with TOC-based chapter detection; OCR fallback for scanned pages
3rd	MOBI	Gets converted to EPUB internally -- if you have the EPUB, use that instead
4th	Markdown	Split on heading levels (# ## ###)
5th	HTML	Split on heading elements (h1/h2/h3), extracts title and author meta
6th	TXT	Detects chapter headings or falls back to fixed-size sections

3. Ingest

bookworm ingest

This scans books/inbox/, extracts text, chunks it, generates embeddings, and stores everything in a local ChromaDB database. You'll see a progress bar for each book.

Verify it worked:

bookworm stats      # How many books/chunks are indexed
bookworm list       # Table of all indexed books

Test a search from the command line:

bookworm search "error handling best practices"
bookworm search "dependency injection" --book "Clean Code" --top-k 3

4. Shell Alias

Add the alias to your shell config so you can run bookworm from anywhere:

# ~/.zshrc or ~/.bashrc
alias bookworm="$HOME/Code/BookWorm/.venv/bin/bookworm"

Then reload: source ~/.zshrc

5. Connect to Claude Code

BookWorm runs as an MCP server -- Claude Code spawns it as a local subprocess and communicates over stdio.

Add the MCP config to one of these locations:

Scope	File	When to use
Global (all projects)	~/.mcp.json	You want your library everywhere
Project-only	<project>/.mcp.json	Scoped to one codebase

{
  "mcpServers": {
    "bookworm": {
      "command": "/absolute/path/to/BookWorm/.venv/bin/python",
      "args": ["-m", "library_mcp.server"],
      "cwd": "/absolute/path/to/BookWorm",
      "env": {
        "PYTHONPATH": "/absolute/path/to/BookWorm/src"
      }
    }
  }
}

Replace /absolute/path/to/BookWorm with the actual path on your machine. A template is provided in claude-code-config.json.

Restart the MCP server by running /mcp in Claude Code and selecting the bookworm server to restart, or start a new session.

6. Install the Plugin (Skills & Slash Commands)

BookWorm includes a Claude Code plugin with slash commands for interactive library use.

Quick start (load for one session only):

claude --plugin-dir /path/to/BookWorm

Permanent install — add these two entries to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "bookworm-local": {
      "source": {
        "source": "directory",
        "path": "/absolute/path/to/BookWorm"
      }
    }
  },
  "enabledPlugins": {
    "bookworm@bookworm-local": true
  }
}

Replace /absolute/path/to/BookWorm with the actual path on your machine. Start a new Claude Code session to pick up the plugin (a simple restart is all it takes — no separate MCP restart needed either, since both the MCP server and plugin load on session start).

7. Auto-Allow Bookworm Tools (optional)

By default, Claude Code will prompt for permission each time it calls a Bookworm MCP tool. Since these are all read-only operations against your local library, you can auto-allow them. Add this to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__bookworm__list_books",
      "mcp__bookworm__search_library",
      "mcp__bookworm__get_chapter",
      "mcp__bookworm__list_sections",
      "mcp__bookworm__get_stats",
      "mcp__bookworm__ingest_path",
      "mcp__bookworm__remove_book"
    ]
  }
}

All three snippets (MCP server, plugin registration, and permissions) are available in claude-code-config.json for easy reference.