{
  "markdown": "# 📚 calibre-mcp\n\n[![npm version](https://img.shields.io/npm/v/calibre-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/calibre-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/calibre-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/calibre-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.caelum29%2Fcalibre--mcp-6E56CF?logo=anthropic)](https://registry.modelcontextprotocol.io)\n[![CI](https://github.com/caelum29/calibre-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/caelum29/calibre-mcp/actions/workflows/ci.yml)\n[![Node](https://img.shields.io/node/v/calibre-mcp?logo=node.js&color=339933)](https://nodejs.org)\n[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n[![skills.sh](https://skills.sh/b/caelum29/calibre-mcp)](https://skills.sh/caelum29/calibre-mcp)\n\n> **The most capable Calibre MCP server in existence** — connect Claude (or any MCP client)\n> to your [Calibre](https://calibre-ebook.com) ebook library and search it by *meaning*, not\n> just keywords.\n\nAsk your AI assistant *“which of my books explain consumer-group rebalancing?”* and get the\nexact chapter — across 800+ books or inside one. Curate metadata, dedupe, and safely edit\nyour library, all through natural language.\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/caelum29/calibre-mcp/main/demo.gif\" width=\"720\" alt=\"Claude Desktop: a plain-language question becomes a semantic search across the library, results render as a 3D cover flow, a click opens the book card, search-inside returns the exact passage with its location, and the figure viewer shows the book's diagrams\" />\n  <br/>\n  <em>One question → semantic search → 3D cover flow → book card → exact passage → figure viewer, all inside Claude Desktop (MCP&nbsp;Apps)</em>\n</p>\n\n## ✨ Highlights\n\n- **19 tools** covering the full surface: search, read content, browse categories, curate,\n  and (opt-in) write — update metadata, bulk-edit, merge duplicates, import, delete, and\n  manage bundles (named topical filters).\n- **Semantic search** — meaning-based, hybrid vector + keyword retrieval over your whole\n  library *or inside a single book*. Multilingual (English + Russian verified,\n  cross-lingual queries work). No other Calibre MCP server has this.\n- **In-chat UI (MCP Apps)** — in hosts that support MCP Apps (Claude Desktop), library\n  searches render an interactive cover carousel, `calibre_get_book` a book detail card\n  with cover, rating, and read/similar actions, and `calibre_get_figures` a figure viewer\n  that shows you the same diagrams the assistant fetched. Text-only hosts are unaffected.\n- **Curation tools** — find duplicates with merge-safety scoring, audit metadata quality,\n  and recover real metadata for books with raw filenames (`795731065.pdf` →\n  *Fundamentals of Software Engineering*) via Open Library / Google Books.\n- **Safe by default** — read-only unless you explicitly enable writes; destructive\n  operations preview first and require confirmation; all writes route through the\n  Content Server so they never race the Calibre GUI.\n\n## 📋 Requirements\n\n- **Calibre** with the **Content Server running** (in Calibre: *Connect/share → Start\n  Content server*). Tested against Calibre 9.x; any recent version should work.\n- **Node.js ≥ 22.5** for the npm/npx install (not needed for the Claude Desktop\n  one-click bundle — Desktop ships its own runtime).\n- Optional, for best PDF text extraction: poppler's `pdftotext`\n  (`brew install poppler`) or Python 3 with PyMuPDF (`pip install pymupdf`). Without\n  them the server falls back to Calibre's `ebook-convert`.\n\n## 🚀 Quick start\n\n### Easiest — let your agent install it for you\n\nGrab the guided-installer skill and hand the whole job to your agent:\n\n```sh\nnpx skills@latest add caelum29/calibre-mcp   # pick calibre-mcp-setup\n```\n\nThen tell your agent: **\"set up calibre-mcp\"**. The `calibre-mcp-setup` skill drives\neverything below — preflight (Node, calibredb, Content Server), the Calibre-side\nconfig, the right install for your client (macOS/Windows/Linux), and a `calibre_ping`\nverification — asking you only the questions that are yours to answer (which client,\nwrites on/off). Works in any Agent-Skills-compatible harness (Claude Code, Copilot,\nAmp, …). Prefer doing it by hand? Pick your client below.\n\n### Claude Code\n\nMCP server only:\n\n```sh\nclaude mcp add calibre -- npx -y calibre-mcp\n```\n\nOr install the plugin — server **and** the companion skills in one step, with a settings\ndialog (server URL, library, write gate) at install time:\n\n```\n/plugin marketplace add caelum29/calibre-mcp\n/plugin install calibre-mcp@caelum29\n```\n\n### Claude Desktop (one-click)\n\nDownload the `.mcpb` bundle from the\n[latest release](https://github.com/caelum29/calibre-mcp/releases/latest) and open it —\nClaude Desktop installs it and prompts for settings (server URL, library, writes on/off).\nNo terminal needed.\n\n> **About the install warning.** Claude Desktop shows *“Installing will grant this\n> extension access to everything on your computer… developer information has not been\n> verified by Anthropic”* for **every** extension installed from a file rather than the\n> built-in directory — it’s not specific to this one. The server runs as a local Node\n> process under your user account, exactly like the `npx` install below; the bundle is\n> built and published by CI from this repository, so you can audit what you’re running.\n> Click **Install** to proceed.\n\n> The bundle ships without the optional embeddings dependency to stay small, so the two\n> semantic-search tools report themselves unavailable. Metadata and full-text search work\n> fully. For semantic search, use the npx install below instead.\n\n### Claude Desktop (JSON config)\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"calibre\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"calibre-mcp\"]\n    }\n  }\n}\n```\n\n### Cowork\n\nConfigure the server in Claude Desktop (either method above) — Desktop bridges local MCP\nservers into Cowork automatically. No extra setup.\n\n### Skills only — any agent (Claude Code, Codex, Cursor, …)\n\nThe repo's Agent Skills — a guided installer (`calibre-mcp-setup`), the calibre-mcp usage\nguide, and the two distill skills — install into any Agent-Skills-compatible harness with\nthe [skills.sh](https://skills.sh) installer:\n\n```sh\nnpx skills@latest add caelum29/calibre-mcp\n```\n\nPick the skills and target agents interactively. Two philosophies, same as\n[mattpocock/skills](https://github.com/mattpocock/skills): **skills.sh copies** the files\ninto your setup so you can hack on them; the **Claude Code plugin** (above) keeps them as a\nmanaged, auto-updating bundle. Either way the skills drive this MCP server's tools, so\ninstall the server too — or let the `calibre-mcp-setup` skill do it: it walks any agent\nthrough preflight, per-client install (macOS/Windows/Linux), and verification.\n\n### First contact — a five-prompt tour\n\nThe server auto-detects your default library; if the Content Server isn’t reachable it\nlogs an actionable hint to stderr. Then try, in order:\n\n1. *“list my calibre libraries”* — connectivity sanity check.\n2. *“find books about Rust”* — metadata search; in Claude Desktop the results render as\n   the cover carousel above.\n3. *“show me The Rust Programming Language”* — full metadata; renders as a book card with\n   cover, rating, and per-format read buttons.\n4. *“show me figure 2.3 from the JWT Handbook”* — the figure arrives as an image for the\n   assistant and, in Claude Desktop, in a figure viewer you can zoom and pan. If the\n   first description doesn’t match what you see, ask *“look at the image — what does it\n   actually show?”*: models sometimes answer figure questions from memory before reading\n   the pixels (the tool result nudges them to look; see Troubleshooting).\n5. *“build the semantic index for my Kafka books”* — one-time prep for meaning-based search\n   (see below).\n6. *“which of my books explain consumer-group rebalancing?”* — semantic search; answers\n   with ranked books, or exact passages when scoped to one book.\n\nBonus: *“what’s wrong with my library?”* runs the quality audit (missing metadata,\nraw-filename titles, invalid ISBNs).\n\n## ✍️ Enabling writes\n\nWrite tools (`calibre_update_book`, `calibre_bulk_update`, `calibre_add_book`,\n`calibre_remove_book`, `calibre_merge_books`, `calibre_manage_bundles`) are **hidden by\ndefault** — including `calibre_manage_bundles`' read-only `list` action, since the gate works\nper tool, not per action. Two independent switches must be on:\n\n1. **The MCP-side gate** — set `CALIBRE_MCP_ENABLE_WRITE=1` (or tick *Enable writes* in\n   the Desktop bundle settings). Without it the write tools aren’t even registered.\n2. **The Calibre-side gate** — the Content Server must allow local writes. **By\n   default the server embedded in the Calibre GUI is read-only**, so either enable\n   the GUI option below or run a standalone server with `--enable-local-write`:\n\n   ```sh\n   # quit the Calibre GUI first (it holds the library lock), then:\n   calibre-server --enable-local-write --port 8080 \"/path/to/Calibre Library\"\n   ```\n\n   Or enable it on the **GUI-embedded** server without quitting the app: open\n   Calibre → **Preferences → Sharing over the net → Advanced** and tick\n   **“Allow un-authenticated local connections to make changes to the library”**\n   (i.e. permit local write access), then restart the Content Server from the GUI.\n   This is the `--enable-local-write` equivalent for the embedded server.\n\nWith only the first switch on, write tools appear but Calibre refuses the write — the\nerror message tells you exactly that. Reads work fine against the GUI-embedded server.\n\nSafety behavior: `calibre_bulk_update` requires an explicit book selection (`ids` or\n`query` — there is no “all books” default) and previews changes until you pass\n`preview: false`. `calibre_remove_book` is a dry-run until you pass `confirm: true`;\ndeletion removes records *and* files, permanently. `calibre_merge_books` shows its full\nmerge plan until you pass `confirm: true`, and trashed sources stay recoverable from\nCalibre's trash (mode `safe` keeps them entirely). `calibre_add_book` only imports files\nfrom whitelisted folders (`CALIBRE_MCP_ADD_ROOTS`).\n\n## 🔎 Semantic search\n\n> Deep dive: [`docs/SEMANTIC-SEARCH.md`](./docs/SEMANTIC-SEARCH.md) — how indexing, hybrid retrieval, and reranking work.\n\nMeaning-based search is **opt-in** and needs two things:\n\n1. **The embeddings dependency** — `@huggingface/transformers` is an\n   `optionalDependencies` entry, so a normal `npx calibre-mcp` / `npm install` gets it\n   automatically. (Only the MCPB bundle excludes it.)\n2. **An index** — ask Claude to run `calibre_build_index` for the books you care about\n   (by ids or a Calibre query). The first build downloads the embedding model\n   (`multilingual-e5-small`, ~118 MB, one-time) into the index directory; after that\n   everything runs offline. Indexing runs at roughly 100 chunks/sec on Apple Silicon.\n\n> [!IMPORTANT]\n> **Search results are sharpened by a cross-encoder reranker whose model is a separate\n> ~576 MB one-time download.** `calibre_build_index` pre-downloads it during the build —\n> the step you already expect to be slow. If you skip straight to searching on a machine\n> without the cached model, your **first** hybrid/vector search triggers that download\n> instead. Reranking also adds seconds of CPU per semantic search; set\n> `CALIBRE_MCP_RERANK=off` to disable it (faster, noticeably less precise ranking).\n\nThen `calibre_semantic_search` answers queries like *“which of my books explain consumer\ngroup rebalancing?”* — across the library (`scope: library`, ranks books) or within one\nbook (`scope: book`, returns located passages). Retrieval is **hybrid** by default:\nvector cosine + stemmed keyword FTS, fused with reciprocal rank fusion, then reranked by\nthe cross-encoder (top 30 candidates) when its model is available. Queries in one\nlanguage find passages in another (EN⇄RU verified).\n\n**No embeddings? Keyword search still works.** `mode: keyword` uses no model *at query\ntime*, but it needs an index. If the embedding model isn’t installed (the default MCPB\nbundle ships without it), build a **keyword-only** index — `calibre_build_index` with\n`keywordOnly: true`, or it happens automatically when the model is absent — and search with\n`mode: keyword`. That path has zero ML dependencies. `mode: vector` then errors actionably\nand `mode: hybrid` degrades to keyword (with a note); rebuild with the model installed\n(`force: true`) to add semantic ranking.\n\n## 🧰 Tools\n\n> Full reference with parameters and examples: [`docs/TOOLS.md`](./docs/TOOLS.md).\n\n| Tool | Access | What it does |\n|---|---|---|\n| `calibre_search` | read | Find books by title/author/ISBN/tag or Calibre query syntax (`mode: meta`), or full text (`mode: fts`); `scope: book` searches inside one book; `filter` scopes to a bundle |\n| `calibre_get_book` | read | Full metadata, formats, and cover link for one book (id or uuid); `include_cover: true` embeds the cover image in the result |\n| `calibre_get_content` | read | Read a book’s text as capped excerpts; walk the whole book via cursor. `structure: true` returns a chapter map (headings, offsets, per-chapter cursors) — EN + RU/UK |\n| `calibre_get_figures`\\* | read | List a book’s figures/illustrations with captions and page locations; fetched ones render in an in-chat figure viewer |\n| `calibre_list_categories` | read | Browse tags, authors, series, publishers, custom columns with counts |\n| `calibre_list_libraries` | read | List the libraries the Content Server exposes (+ which is default) |\n| `calibre_semantic_search` | read | Meaning-based search; `mode: hybrid\\|vector\\|keyword`, library- or book-scoped; `filter` scopes to a bundle |\n| `calibre_build_index` | read* | Build/refresh the local semantic index for selected books (writes only a local index file); `keywordOnly: true` builds a model-free keyword index |\n| `calibre_find_duplicates` | read | Duplicate groups with merge-safety scores; `mode: compare` diffs two books |\n| `calibre_quality_report` | read | Audit: missing metadata, raw-filename titles, invalid ISBNs, author-sort issues, series gaps |\n| `calibre_recover_metadata` | read | Propose real metadata via Open Library → Google Books; **preview-only**, apply with `calibre_update_book` |\n| `calibre_extract_isbn` | **write** | Scan a book’s own text for a valid ISBN and set its `isbn` identifier; preview-first, apply with `apply: true` |\n| `calibre_update_book` | **write** | Set metadata fields on one book (incl. `#custom` columns); returns the applied diff |\n| `calibre_bulk_update` | **write** | Same change across a set of books; selection required, preview-first |\n| `calibre_add_book` | **write** | Import a local ebook file (path-whitelisted) |\n| `calibre_remove_book` | **write, destructive** | Permanently delete books (records + files); dry-run unless confirmed |\n| `calibre_merge_books` | **write, destructive** | Merge duplicate records: move formats into a target, merge metadata per Calibre's rules, trash sources; dry-run plan unless confirmed |\n| `calibre_manage_bundles` | **write** | List/create/update/delete Bundles — named topical filters backed by Calibre saved searches; `-`-named bundles auto-hide their books from discovery searches; preview-first |\n| `calibre_ping` | read | Health check: is Calibre reachable end-to-end? |\n\n\\* Figures reach the assistant as real images, but models sometimes describe a figure from\nmemory before looking at it — if the first description doesn’t match the picture, re-ask\nwith *“look at the image — what does it actually show?”* (details in\n[Troubleshooting](./docs/TROUBLESHOOTING.md#the-assistant-describes-a-figure-wrongly-on-the-first-try)).\n\nIn MCP Apps hosts, `calibre_search` and `calibre_semantic_search` (library scope) render\ntheir results as a cover-board carousel, `calibre_get_book` as a book card, and\n`calibre_get_figures` as a figure viewer (reading pane + margin rail, click to zoom to 100%)\nso you see the diagrams the assistant is reading — covers load from your local Content\nServer. Everywhere else the same tools return their usual text results; no configuration\nneeded either way.\n\n## 📚 Companion skill: calibre-distill\n\nAn Agent Skill that distills a book from your library into a reusable, structured skill\n(frameworks, mental models, glossary, cheatsheet) by driving the tools above — the chapter\nmap (`calibre_get_content structure=true`) plus in-book keyword + semantic search. Works on\nEN and RU/UK books, no temp files, and can optionally stamp what you learned back into the\ncatalog (tags + a distill note) through the gated write tools.\n\nIt ships in this repo at [`skills/calibre-distill/`](./skills/calibre-distill). Install it\nvia `npx skills@latest add caelum29/calibre-mcp` or the Claude Code plugin (see\n[Quick start](#-quick-start)), or manually by symlinking:\n\n```sh\nln -s \"$PWD/skills/calibre-distill\" ~/.claude/skills/calibre-distill\n```\n\nThen ask, e.g., *“distill book 187 into a skill called kafka-ops”*. Note: the MCPB bundle\ncan’t ship skills — install the skills separately from the MCP server on Claude Desktop.\n\n### Companion skill: calibre-distill-topic\n\nA sibling skill that synthesizes **one topic across several books** (≥3) into a single\n**concept-keyed** skill — a decision framework, per-concept sections, a cross-source config\ntable, an explicit *“where the sources disagree or complement”* section, and an ISBN\nbibliography that doubles as a live-source binding. Use it when you want a topic study aid\nbuilt from a shelf of books rather than a single-book distill (single-book requests belong\nto `calibre-distill`). Ships at [`skills/calibre-distill-topic/`](./skills/calibre-distill-topic);\ninstalled by the same skills.sh / plugin / symlink paths as above.\n\nThen ask, e.g., *“synthesize kafka reliability from books 187 182 571 186 into a skill.”*\n\nGenerated skills can be checked with the bundled verifier — verbatim-overlap (8-gram\nshingles vs the source books), quote budget, compression floor, heading mirroring,\ncursor leaks, and attribution:\n\n```sh\npnpm build && node scripts/legal-gate.mjs <skill-dir> --book <id> [--book <id>…]\n```\n\n## ⚙️ Configuration\n\nEverything is optional — with a running Content Server on the default port, zero config\nworks. Environment variables (the Desktop bundle exposes the same settings as UI fields):\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `CALIBRE_MCP_SERVER_URL` | `http://localhost:8080` | Calibre Content Server base URL |\n| `CALIBRE_MCP_LIBRARY` | *auto-detect* | Library name; empty = the server’s default library |\n| `CALIBRE_MCP_ENABLE_WRITE` | off | Master write gate (`1`/`true`/`yes`) |\n| `CALIBRE_MCP_CALIBREDB_PATH` | *auto-discover* | `calibredb` binary; found via standard install paths, then `PATH` |\n| `CALIBRE_MCP_INDEX_DIR` | platform data dir¹ | Semantic index + embedding-model cache |\n| `CALIBRE_MCP_SEMANTIC_FLOOR` | `0.78` | Cosine score below which semantic results are flagged low-confidence |\n| `CALIBRE_MCP_RERANK` | on | Cross-encoder rerank stage on semantic search (~576 MB model, seconds of CPU per query); set `off`/`false`/`0` to disable |\n| `CALIBRE_MCP_MAX_BOOK_BYTES` | `268435456` (256 MB) | Largest book download `calibre_build_index` / `calibre_get_content` will extract; bigger books are skipped² |\n| `CALIBRE_MCP_ADD_ROOTS` | `~/Documents`, `~/Downloads` | Folders `calibre_add_book` may import from (path-delimiter separated) |\n| `CALIBRE_MCP_BOARD_STYLE` | `shelf` | Search-results widget style in MCP Apps hosts: `shelf` (scrolling cover shelf) or `coverflow` (3D cover flow; the Desktop bundle exposes this as a *Coverflow search results* toggle) |\n\n¹ macOS `~/Library/Application Support/calibre-mcp/index`, Windows\n`%APPDATA%\\calibre-mcp\\index`, Linux `$XDG_DATA_HOME/calibre-mcp/index`.\n\n² Size the cap against what the **Content Server serves**, not the file on disk — it can hand\nback a much heavier copy (an 8 MB PDF served as 70 MB), so a disk-sized cap silently skips books.\n\n## 🩺 Troubleshooting\n\n> More symptoms and fixes: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md).\n\n- **“Calibre unreachable” / connection refused** — the Content Server isn’t running.\n  In Calibre: *Connect/share → Start Content server*, or point\n  `CALIBRE_MCP_SERVER_URL` at the right host/port.\n- **Write refused / “Forbidden”** — the Content Server doesn’t allow local writes.\n  See *Enabling writes* above: run a standalone server with\n  `--enable-local-write`, or tick the GUI’s *Sharing over the net → Advanced* option\n  and restart the Content Server.\n- **Full-text search returns nothing / errors** — Calibre’s FTS index isn’t enabled for\n  the library. In Calibre: *Preferences → Searching → Full text search*, enable it, and\n  let indexing finish (it can take a while on large libraries).\n- **“embedding model unavailable”** — the optional `@huggingface/transformers` package\n  isn’t installed (expected with the MCPB bundle). Use the npx install, or\n  `npm install @huggingface/transformers` next to the server. To search without it, build a\n  keyword-only index (`calibre_build_index keywordOnly=true`) and use `mode: keyword`.\n- **`calibredb` not found** — install Calibre, or set `CALIBRE_MCP_CALIBREDB_PATH` to\n  the binary (macOS: `/Applications/calibre.app/Contents/MacOS/calibredb`).\n- **A PDF extracts to empty text** — it’s a scanned/image PDF; Calibre has no OCR, and\n  neither do we.\n- **Library not found (404)** — pass the library’s *display name* or *ID* as shown by\n  `calibre_list_libraries`; when in doubt, leave the library unset and let the server\n  pick its default.\n\n## 🛠️ Development\n\n```sh\npnpm install\npnpm build        # tsc → dist/\npnpm test         # vitest (unit; no network, no model download)\npnpm test:model   # gated embedding-model integration tests (~118 MB download)\npnpm inspect      # MCP Inspector against the built server\npnpm pack:mcpb    # build the Claude Desktop .mcpb bundle\n```\n\nThe codebase is Clean Architecture: tool handlers, Calibre clients, and the semantic\ncore are SDK-free; only `src/server.ts` touches the MCP SDK. User docs — the tool\nreference and the semantic-search guide — live in [`docs/`](./docs).\n\nQuestions, ideas, and setups welcome in\n[**Discussions**](https://github.com/caelum29/calibre-mcp/discussions); bug reports and PRs\nin [Issues](https://github.com/caelum29/calibre-mcp/issues).\n\n## 📄 License\n\n[MIT](./LICENSE) © 2026 Artem Sorochynskyi\n\nAn independent project, not affiliated with Calibre.\n[Calibre](https://calibre-ebook.com) itself is\n[Kovid Goyal's open-source project](https://github.com/kovidgoyal/calibre) (GPLv3) —\nthis server drives it as a separate program via `calibredb` and the Content Server.\n",
  "bytes": 22828,
  "sha": "bd57b05df296c3902b5efcadbd0cb1e59a53c333ce21bd51a1e15981a0ec5c00",
  "repo_slug": "caelum29/calibre-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_caelum29_calibre_mcp_3244e4ec/readme"
}