calibre-mcp

# 📚 calibre-mcp

[![npm version](https://img.shields.io/npm/v/calibre-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/calibre-mcp)
[![npm downloads](https://img.shields.io/npm/dm/calibre-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/calibre-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.caelum29%2Fcalibre--mcp-6E56CF?logo=anthropic)](https://registry.modelcontextprotocol.io)
[![CI](https://github.com/caelum29/calibre-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/caelum29/calibre-mcp/actions/workflows/ci.yml)
[![Node](https://img.shields.io/node/v/calibre-mcp?logo=node.js&color=339933)](https://nodejs.org)
[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
[![skills.sh](https://skills.sh/b/caelum29/calibre-mcp)](https://skills.sh/caelum29/calibre-mcp)

> **The most capable Calibre MCP server in existence** — connect Claude (or any MCP client)
> to your [Calibre](https://calibre-ebook.com) 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

- **17 tools** covering the full surface: search, read content, browse categories, curate,
  and (opt-in) write — update metadata, bulk-edit, merge duplicates, import, delete.
- **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 and `calibre_get_book` a book detail card
  with cover, rating, and read/similar actions. 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:

```sh
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:

```sh
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](https://github.com/caelum29/calibre-mcp/releases/latest) 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`:

```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](https://skills.sh) installer:

```sh
npx skills@latest add caelum29/calibre-mcp
```

Pick the skills and target agents interactively. Two philosophies, same as
[mattpocock/skills](https://github.com/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. *“build the semantic index for my Kafka books”* — one-time prep for meaning-based search
   (see below).
5. *“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`) are **hidden by default**. 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`:

   ```sh
   # 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`](./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, o