📚 calibre-mcp

The most capable Calibre MCP server in existence — connect Claude (or any MCP client) to your Calibre ebook library and search it by meaning, not just keywords.

Ask your AI assistant “which of my books explain consumer-group rebalancing?” and get the exact chapter — across 800+ books or inside one. Curate metadata, dedupe, and safely edit your library, all through natural language.

<p align="center"> <img src="https://raw.githubusercontent.com/caelum29/calibre-mcp/main/demo.gif" width="720" alt="Claude Desktop searching a Calibre library and rendering the results as an interactive cover carousel" /> <br/> <em>Claude Desktop rendering a library search as an interactive cover board (MCP&nbsp;Apps)</em> </p>

✨ Highlights

• 19 tools covering the full surface: search, read content, browse categories, curate, and (opt-in) write — update metadata, bulk-edit, merge duplicates, import, delete, and manage bundles (named topical filters).
• Semantic search — meaning-based, hybrid vector + keyword retrieval over your whole library or inside a single book. Multilingual (English + Russian verified, cross-lingual queries work). No other Calibre MCP server has this.
• In-chat UI (MCP Apps) — in hosts that support MCP Apps (Claude Desktop), library searches render an interactive cover carousel, calibre_get_book a book detail card with cover, rating, and read/similar actions, and calibre_get_figures a figure viewer that shows you the same diagrams the assistant fetched. Text-only hosts are unaffected.
• Curation tools — find duplicates with merge-safety scoring, audit metadata quality, and recover real metadata for books with raw filenames (795731065.pdf → Fundamentals of Software Engineering) via Open Library / Google Books.
• Safe by default — read-only unless you explicitly enable writes; destructive operations preview first and require confirmation; all writes route through the Content Server so they never race the Calibre GUI.

📋 Requirements

• Calibre with the Content Server running (in Calibre: Connect/share → Start Content server). Tested against Calibre 9.x; any recent version should work.
• Node.js ≥ 22.5 for the npm/npx install (not needed for the Claude Desktop one-click bundle — Desktop ships its own runtime).
• Optional, for best PDF text extraction: poppler's pdftotext (brew install poppler) or Python 3 with PyMuPDF (pip install pymupdf). Without them the server falls back to Calibre's ebook-convert.

🚀 Quick start

Easiest — let your agent install it for you

Grab the guided-installer skill and hand the whole job to your agent:

npx skills@latest add caelum29/calibre-mcp   # pick calibre-mcp-setup

Then tell your agent: "set up calibre-mcp". The calibre-mcp-setup skill drives everything below — preflight (Node, calibredb, Content Server), the Calibre-side config, the right install for your client (macOS/Windows/Linux), and a calibre_ping verification — asking you only the questions that are yours to answer (which client, writes on/off). Works in any Agent-Skills-compatible harness (Claude Code, Copilot, Amp, …). Prefer doing it by hand? Pick your client below.

Claude Code

MCP server only:

claude mcp add calibre -- npx -y calibre-mcp

Or install the plugin — server and the companion skills in one step, with a settings dialog (server URL, library, write gate) at install time:

/plugin marketplace add caelum29/calibre-mcp
/plugin install calibre-mcp@caelum29

Claude Desktop (one-click)

Download the .mcpb bundle from the latest release and open it — Claude Desktop installs it and prompts for settings (server URL, library, writes on/off). No terminal needed.

About the install warning. Claude Desktop shows “Installing will grant this extension access to everything on your computer… developer information has not been verified by Anthropic” for every extension installed from a file rather than the built-in directory — it’s not specific to this one. The server runs as a local Node process under your user account, exactly like the npx install below; the bundle is built and published by CI from this repository, so you can audit what you’re running. Click Install to proceed.

The bundle ships without the optional embeddings dependency to stay small, so the two semantic-search tools report themselves unavailable. Metadata and full-text search work fully. For semantic search, use the npx install below instead.

Claude Desktop (JSON config)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "calibre": {
      "command": "npx",
      "args": ["-y", "calibre-mcp"]
    }
  }
}

Cowork

Configure the server in Claude Desktop (either method above) — Desktop bridges local MCP servers into Cowork automatically. No extra setup.

Skills only — any agent (Claude Code, Codex, Cursor, …)

The repo's Agent Skills — a guided installer (calibre-mcp-setup), the calibre-mcp usage guide, and the two distill skills — install into any Agent-Skills-compatible harness with the skills.sh installer:

npx skills@latest add caelum29/calibre-mcp

Pick the skills and target agents interactively. Two philosophies, same as mattpocock/skills: skills.sh copies the files into your setup so you can hack on them; the Claude Code plugin (above) keeps them as a managed, auto-updating bundle. Either way the skills drive this MCP server's tools, so install the server too — or let the calibre-mcp-setup skill do it: it walks any agent through preflight, per-client install (macOS/Windows/Linux), and verification.

First contact — a five-prompt tour

The server auto-detects your default library; if the Content Server isn’t reachable it logs an actionable hint to stderr. Then try, in order:

1. “list my calibre libraries” — connectivity sanity check.
2. “find books about Rust” — metadata search; in Claude Desktop the results render as the cover carousel above.
3. “show me The Rust Programming Language” — full metadata; renders as a book card with cover, rating, and per-format read buttons.
4. “show me figure 2.3 from the JWT Handbook” — the figure arrives as an image for the assistant and, in Claude Desktop, in a figure viewer you can zoom and pan.
5. “build the semantic index for my Kafka books” — one-time prep for meaning-based search (see below).
6. “which of my books explain consumer-group rebalancing?” — semantic search; answers with ranked books, or exact passages when scoped to one book.

Bonus: “what’s wrong with my library?” runs the quality audit (missing metadata, raw-filename titles, invalid ISBNs).

✍️ Enabling writes

Write tools (calibre_update_book, calibre_bulk_update, calibre_add_book, calibre_remove_book, calibre_merge_books, calibre_manage_bundles) are hidden by default — including calibre_manage_bundles' read-only list action, since the gate works per tool, not per action. Two independent switches must be on:

1. The MCP-side gate — set CALIBRE_MCP_ENABLE_WRITE=1 (or tick Enable writes in the Desktop bundle settings). Without it the write tools aren’t even registered.

2. The Calibre-side gate — the Content Server must allow local writes. By default the server embedded in the Calibre GUI is read-only, so either enable the GUI option below or run a standalone server with --enable-local-write:

   # quit the Calibre GUI first (it holds the library lock), then:
   calibre-server --enable-local-write --port 8080 "/path/to/Calibre Library"
   

   Or enable it on the GUI-embedded server without quitting the app: open Calibre → Preferences → Sharing over the net → Advanced and tick “Allow un-authenticated local connections to make changes to the library” (i.e. permit local write access), then restart the Content Server from the GUI. This is the --enable-local-write equivalent for the embedded server.

With only the first switch on, write tools appear but Calibre refuses the write — the error message tells you exactly that. Reads work fine against the GUI-embedded server.

Safety behavior: calibre_bulk_update requires an explicit book selection (ids or query — there is no “all books” default) and previews changes until you pass preview: false. calibre_remove_book is a dry-run until you pass confirm: true; deletion removes records and files, permanently. calibre_merge_books shows its full merge plan until you pass confirm: true, and trashed sources stay recoverable from Calibre's trash (mode safe keeps them entirely). calibre_add_book only imports files from whitelisted folders (CALIBRE_MCP_ADD_ROOTS).

🔎 Semantic search

Deep dive: docs/SEMANTIC-SEARCH.md — how indexing, hybrid retrieval, and reranking work.

Meaning-based search is opt-in and needs two things:

1. The embeddings dependency — @huggingface/transformers is an optionalDependencies entry, so a normal npx calibre-mcp / npm install gets it automatically. (Only the MCPB bundle excludes it.)
2. An index — ask Claude to run calibre_build_index for the books you care about (by ids or a Calibre query). The first build downloads the embedding model (multilingual-e5-small, ~118 MB, one-time) into the index directory; after that everything runs offline. Indexing runs at roughly 100 chunks/sec on Apple Silicon.

[!IMPORTANT] Search results are sharpened by a cross-encoder reranker whose model is a separate ~576 MB one-time download. calibre_build_index pre-downloads it during the build — the step you already expect to be slow. If you skip straight to searching on a machine without the cached model, your first hybrid/vector search triggers that download instead. Reranking also adds seconds of CPU per semantic search; set CALIBRE_MCP_RERANK=off to disable it (faster, noticeably less precise ranking).

Then calibre_semantic_search answers queries like “which of my books explain consumer group rebalancing?” — across the library (scope: library, ranks books) or within one book (scope: book, returns located passages). Retrieval is hybrid by default: vector cosine + stemmed keyword FTS, fused with reciprocal rank fusion, then reranked by the cross-encoder (top 30 candidates) when its model is available. Queries in one language find passages in another (EN⇄RU verified).

No embeddings? Keyword search still works. mode: keyword uses no model at query time, but it needs an index. If the embedding model isn’t installed (the default MCPB bundle ships without it), build a keyword-only index — calibre_build_index with keywordOnly: true, or it happens automatically when the model is absent — and search with mode: keyword. That path has zero ML dependencies. `mode: ve