mcp-calibre

🇬🇧 English · 🇮🇹 Italiano

Your Calibre library, readable by your AI assistant: private, read-only, fast.

mcp-calibre is an MCP server that lets Claude, ChatGPT, Codex and any other MCP
client search, read and understand the books in your local Calibre library. It reads
Calibre's own databases directly (no Calibre process needed, no write access, ever) and adds what an assistant
needs to really work with a library: full-text search, search by meaning, reading by chapter, images, OCR for
scanned PDFs, library cleanup, and a check that notes written from books do not copy them.

Install it · Tweak it and see how it works · Skills · FAQ · Performance

Why you will like it

• Private and read-only. Everything runs on your machine. Calibre's databases are opened read-only, there are
  no write tools and no shell: the server cannot change your library. Only what a tool returns reaches your AI client.
• Three ways to search. By metadata, with Calibre's own search syntax; by exact words, ranked full-text
  search; and by meaning, with multilingual semantic search (ask in Italian, find English passages).
• Reads books properly. A chapter map for every format, LIT and MOBI included: read one chapter, a page
  range, or the passage around a search hit.
• Shows images in the chat. Covers and figures appear inline, with Copy and Save PNG buttons, without spending
  model tokens.
• Understands scanned PDFs. OCR with Tesseract turns them into searchable, readable text, in a batch command
  that never slows a conversation.
• Cleans up the library. A metadata quality report, duplicates compared field by field, ISBNs found in the text.
• Turns books into skills and agents. Four companion skills in skills/ go well beyond search.
  calibre-distill distills one book into a reusable skill of your own (frameworks, decision guide, glossary,
  checklists). calibre-distill-topic synthesises a topic across three or more books and shows where the sources
  agree and disagree. calibre-book-agent turns a book into an agent that applies its approach and checks the
  book before claiming what it says. calibre-book-redteam stress-tests a book's claims against the rest of your
  library. All four end with a legal gate that checks the notes do not copy the books. The skills manual
  explains each one.
• Fast. Searches answer in milliseconds on a library of 1,500 books (numbers below).

What you can ask

Display verbatim quotations in the HTML view with calibre_show_quotes, passing
passages: [{book_id: 1168, format: "EPUB", offset: 1200, max_chars: 500}].
The server extracts the passage from the book and sends it only in MCP Apps view metadata (_meta);
the chat response contains references only. The view shows the title, authors, format and character
range in extracted text (not page numbers). The client must forward _meta to the view;
without this support, passages are neither displayed nor automatically copied into chat.
After upgrading to 5.4.0, restart the server and refresh the client's MCP connection to discover the
new tool. See Verbatim quotations for limits,
exact character ranges and troubleshooting.

In total: 31 tools, 4 resources and 5 prompts, all read-only. The full list is in the
tools reference.

Books that work for you

Searching is only the start. Four ready-made skills in skills/ put your books to work:

• Turn a book into a method. Hand over a management, negotiation or engineering book and get back a skill that
  your assistant applies to your own situation, written in its own words and checked so that it does not copy the book.
• Give a book a voice. Make an agent that thinks the way one book does, checks the book before it says what the
  book claims, cites the chapter, and admits "the book is silent" when it is.
• Let two books argue. Put two of those agents on the same problem and let them debate it, or build a plan
  together: each defends its book, concedes where the other is stronger, and says what would change its mind. You
  set up the exchange; the manual has the recipe.
• Find out whether a book holds up. Its central claims are checked against the rest of your library, the book's
  best defence first, and you get a verdict per claim: supported, qualified, contested or contradicted, and by which
  of your books.
• Map a whole shelf. Ask what five books say about one subject and get a guide organized by concept that shows
  where they agree, where they complement each other and where they disagree.

Every result ends with a legal gate that checks it is a transformation and not a copy of the books.

How the skills work, with examples and a step-by-step recipe for book against book

How it works

flowchart LR
  AI["AI client<br/>Claude · ChatGPT · Codex · any MCP client"] -- "MCP: stdio or HTTP" --> S["mcp-calibre<br/>read-only server"]
  S -- "read only" --> L[("Calibre library<br/>metadata.db · full-text-search.db · books")]
  S <--> X[("Sidecar cache<br/>full-text · semantic · figure indexes")]

1. The client talks MCP to the server. Over stdio (Claude Desktop, ChatGPT desktop app, Codex) or over
   Streamable HTTP (Claude Code, other clients, a shared server).
2. The server reads Calibre's databases directly, in read-only mode: no calibredb process to start, queries
   in milliseconds, and it works while Calibre is open.
3. A small sidecar cache makes content searchable. Calibre stores the extracted text of your books but with a
   tokenizer other programs cannot query, so the server keeps its own full-text index, updated incrementally. The
   optional semantic and figure indexes live next to it. The cache is the only thing the server writes, and it is
   always safe to delete.
4. Books are read on demand. Calibre's text first, then a built-in EPUB parser, PyMuPDF for PDFs, and
   Calibre's ebook-convert for LIT, MOBI and the rest. Scanned PDFs are OCRed in a batch step.

Visual overview of the core server (read-only access, sidecar full-text index, extraction chain, transports). The
precise, current reference is Under the hood, including the semantic and figure indexes added in 5.0.

Performance at a glance

Measured on a synthetic library of 1,500 books (524 MB of text) on a single CPU core (2.1 GHz Intel Xeon), with the
benchmark that ships in the repository (tests/bench_synthetic.py):

* measured with the offline hash embedding backend: it exercises the index and the ranking, not the speed of the real model.

These figures show how the server scales, not what your own books will do: real libraries have PDFs, LIT and
MOBI files, and slower disks. Method, full results, sizing of the semantic index and tuning are in the
performance manual.

Quick start

You need Windows 10/11, Python 3.10 or newer (64-bit) and Calibre with full-text
indexing enabled. Then, either with the graphical wizard:

git clone https://github.com/jumpifequal/mcp-calibre C:\Tools\mcp-calibre
C:\Tools\mcp-calibre\setup-wizard.bat

or with a single command:

cd C:\Tools\mcp-calibre
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Library "D:\Books\Calibre Library" -Pdf pymupdf -Register

Fully restart Claude Desktop (quit it from the tray icon): it starts the server by itself, there is nothing else
to launch. Then ask: "which books in my library explain prompt
injection?" The installation manual covers the three routes (wizard, script, manual),
other clients, and how to check that everything works.

The setup wizard and the console

Two optional Windows tools take the command line out of the way. setup-wizard.bat checks your PC, picks your
library and installs for you; console.bat starts and watches the server and runs the maintenance jobs, with live
progress and with errors and warnings kept apart from the rest.

Setup wizard: pre-flight checks, then the choice of components (an illustration drawn from the wizard's layout; the real window uses Windows' native controls).

Console: the server running with its library status and a warning kept in the Problems panel (left); a semantic-index build of 300 synthetic books in progress, with its live log and progress bar (right).

How to use them: setup wizard · console.

Works with

ChatGPT on the web and claude.ai custom connectors cannot use it: they only reach public HTTPS endpoints with OAuth,
which is not a supported way to expose a personal library.

Documentation

Safety in brief

• Read-only by design: SQLite connections in mode=ro, no write tools, no shell; the only writes are to the
  server's own cache.
• HTTP needs a bearer token (loopback bind by default); --no-auth is refused anywhere but loopback.
• Book text, annotations and image text are third-party content: the server tells the model never to follow
  instructions found in them, but avoid combining it with high-impact tools (email sending, shell, browser) in the
  same session.
• The full list is in Security notes.
• An independent trust index, M8ven, scans the code: its badge at the top shows the current score. New projects are capped at grade C until they earn adoption.

Background

The idea of exposing a Calibre library through MCP was first explored by the bash-based
trieloff/calibre-mcp. This project is an independent implementation
and shares no code with it.

Licence

Apache-2.0.