Skip to main content
Glama
calibre-mcp

calibre-mcp

by ZehuiTIAN

calibre-mcp

An MCP server that gives AI assistants (Claude Code, Claude Desktop, Cursor, ...) read and write access to your local Calibre ebook library.

Search the library, browse recent additions, import new ebooks with automatic duplicate detection, and manage a "drop folder" inbox — all from chat.

  • Zero-config on a normal setup: the calibredb executable and the library your Calibre GUI is using are discovered automatically on macOS, Windows and Linux.

  • Locale-independent: all reads go through calibredb --for-machine (JSON), so results never depend on your Calibre interface language.

  • Safe by default: duplicate detection relies on Calibre itself — a book whose title + author is already in the library is skipped, never imported twice.

  • Reads book contents: a local full-text index (with CJK support) plus paged text reading, built on Calibre's own converter — great for quoting and summarising.

Tools

Tool

Description

library_info

Library path, number of books, calibre version

search_books

Full calibre query language search (author:asimov, title:"i robot", tags:python, ...)

list_books

Browse the library, defaults to most recently added first

add_books

Import ebook files or whole directories, with duplicate detection

import_inbox

Import everything in the inbox folder and file it away

build_index

One-time index of book contents for full-text search

search_in_book

Search inside book contents, returning match snippets

read_book

Read a book's plain text page by page (converted on demand)

detect_scanned_books

Find books whose PDF is scanned (no text layer)

ocr_book

OCR a scanned PDF via a cloud provider, index it, and re-typeset it into an EPUB

ocr_scanned_books

Batch-OCR every scanned book in the library (resumable)

Related MCP server: Calibre MCP Server

Requirements

  • Calibre (any version that ships calibredb; tested with 9.x)

  • Python ≥ 3.10

Installation

pipx install calibre-mcp

uv

uv tool install calibre-mcp

pip

pip install calibre-mcp

From source

git clone https://github.com/ZehuiTIAN/calibre-mcp.git
cd calibre-mcp
pip install -e ".[dev]"     # dev extras add pytest + ruff

Configuration

Everything is optional on a normal setup; each value can be pinned with an environment variable.

Variable

Meaning

Default

CALIBRE_LIBRARY_PATH

Library directory to use

The library your Calibre GUI uses (most-used library from gui.json, else the default library)

CALIBREDB_PATH

Path to the calibredb executable

calibredb on PATH, then platform install locations (macOS app bundle, C:\Program Files\Calibre2\)

CALIBRE_INBOX_DIR

Drop folder for import_inbox

Disabled (tool errors if used)

CALIBRE_TEXT_CACHE_DIR

Where converted text + search index live

OS temp dir (not persistent across reboots)

CALIBREDB_TIMEOUT

Seconds before a calibredb call is aborted

300

CALIBRE_OCR_PROVIDER

OCR backend (anthropic)

anthropic

CALIBRE_OCR_API_KEY

API key for the OCR backend

— (required for ocr_book)

CALIBRE_OCR_MODEL

Model for the OCR backend

provider default

CALIBRE_OCR_BASE_URL

Optional API base URL override (proxies/gateways)

—

CALIBRE_OCR_MAX_PAGES

Page cap per ocr_book run

500

Registering with Claude Code

claude mcp add calibre-mcp -- calibre-mcp

or add to ~/.claude.json → mcpServers (user scope):

"calibre_mcp": {
  "type": "stdio",
  "command": "calibre-mcp",
  "args": [],
  "env": {
    "CALIBRE_LIBRARY_PATH": "/path/to/your/library",
    "CALIBRE_INBOX_DIR": "/path/to/your/inbox"
  }
}

Registering with Claude Desktop / Cursor

Add the same JSON block to the MCP servers section of claude_desktop_config.json (Claude Desktop) or Cursor's MCP settings.

Inbox workflow

A drop folder makes a pleasant "find → drop → archive" loop for books you download by hand:

  1. Point CALIBRE_INBOX_DIR at a folder, e.g. ~/Downloads/Calibre-Inbox.

  2. Download ebooks into that folder.

  3. Ask your assistant to run import_inbox.

Every file is added to the library; successfully added files and duplicates are filed under imported/YYYY-MM/, failures under failed/ — the inbox itself stays clean, and nothing is ever overwritten (name collisions get a -1, -2, ... suffix).

Supported extensions: .epub .pdf .mobi .azw .azw3 .djvu .cbz .cbr .fb2 .txt .md .docx .rtf .lit .prc .pdb .chm .htmlz.

Full-text search & reading

To search inside book contents or quote a passage, index the library once:

  1. (Optional) point CALIBRE_TEXT_CACHE_DIR at a persistent location — the default cache lives in the OS temp directory.

  2. Ask your assistant to run build_index. A first run converts every book with Calibre's converter; expect roughly a second or two per book (PDFs take longer). Later calls skip books that are already indexed.

Then:

  • search_in_book("机器学习与深度学习", book_id=42) — substring search, works for Chinese without word segmentation and for English; queries shorter than three characters fall back to a linear scan so two-character Chinese words still match.

  • read_book(42, offset=0, limit=12000) — paged plain-text reading; responses carry next_offset and total_chars.

The index and converted texts live outside the library (a cache directory); the library itself is never modified by these tools. Note that calibre's own built-in full-text search is not used: its background indexing does not reliably extract text outside the GUI on some platforms, and a self-contained index behaves identically everywhere.

OCR for scanned PDFs

Calibre has no OCR: a scanned PDF (pages are photos, no text layer) converts to an EPUB full of page images and stays unsearchable. calibre-mcp closes that gap with a pluggable cloud OCR pipeline:

pip install "calibre-mcp[ocr]"     # adds pymupdf + the anthropic SDK
  1. Set CALIBRE_OCR_API_KEY (and optionally CALIBRE_OCR_PROVIDER / CALIBRE_OCR_MODEL / CALIBRE_OCR_BASE_URL).

  2. detect_scanned_books() — lists books whose PDF has no usable text layer (no key needed for detection).

  3. ocr_book(42) — renders the pages, sends them to the provider (default: the Anthropic Messages API, 8 pages per request), caches the structured markdown, indexes it for search_in_book / read_book, then typesets a clean EPUB with pandoc and attaches it to the existing book record (replacing any previous EPUB).

  4. ocr_scanned_books(limit=10) — batch mode: OCR every scanned book in the library, skipping already-OCR'd ones. Repeat the call to work through a large library; per-batch caching makes every interruption resumable.

The provider interface is two methods (ocr_pages); adding Azure Document Intelligence or Aliyun/Baidu OCR means implementing that interface and registering it in ocr.PROVIDERS.

Provider choice: for Chinese books, Alibaba Cloud Bailian qwen-vl-ocr is the default recommendation — purpose-built document OCR with layout output, priced at roughly ¥0.3 for a 200-page book (≈1/20 the cost of a general vision LLM). Full comparison, official links and sign-up steps: docs/OCR_PROVIDERS.md(中文).

API key isolation: keys are per-user — set them in your MCP client config only, never in the repository. Nothing in this project reads keys from files or embeds them; each user brings their own key.

Caveats

  • Database lock: while the Calibre GUI has the library open, write operations (add_books, import_inbox) can fail with a database lock error. Read-only tools keep working. Close Calibre (or switch it to another library) before importing.

  • Large libraries: add_books/import_inbox snapshot the full set of book ids around each add, which is fast in practice but is O(number of books) per import.

  • This tool only organizes your library. It contains no search or download functionality; use it with content you have the right to hold.

Development

pip install -e ".[dev]"
ruff check .
pytest -m "not integration"      # unit tests, run anywhere
pytest                           # + integration tests (need local calibre)

Integration tests create throwaway libraries under /tmp and never touch your real library.

License

MIT — see LICENSE.


中文速览

把本地 Calibre 书库接给 Claude/Cursor 等 AI 助手的 MCP 服务器:十二个工具 (元数据搜索/浏览/导入查重/收件箱归档 + build_index/search_in_book/ read_book 全文检索与读正文 + detect_scanned_books/ocr_book/ ocr_scanned_books 扫描书云端 OCR 与批量重排版),自动发现 calibredb 和 书库位置,全平台(Windows/macOS/Linux)开箱即用。仓库自带 CLAUDE.md, AI 助手拉下来即可按指引完成安装与 API 配置。

pipx install calibre-mcp
claude mcp add calibre-mcp -- calibre-mcp

导入时自动查重(书名+作者相同的书不会被重复导入);配合 CALIBRE_INBOX_DIR 收件箱目录,把下载的书丢进去、说一句"导入收件箱"即可 归档,处理完的文件自动归类到 imported/ 或 failed/。

想引用书里内容:先跑一次 build_index 建全文索引(中文子串可直接搜), 之后 search_in_book 定位段落、read_book 分页读正文。

注意:Calibre 桌面程序打开着同一书库时,写入操作可能因数据库锁失败, 导入前先关闭 Calibre。

Available Tools

11 tools
add_booksA

Import ebook files (or directories of ebooks) into the library.

Books whose title + author are already in the library are skipped by calibre and reported as "duplicate". The Calibre GUI must not hold the library open while adding.

Args: paths: Absolute paths to ebook files or folders containing ebooks.

Inputs: paths (required). Returns: object

build_indexA

Index book contents for full-text search (one-time, cached).

Converts each book's text with calibre's converter and stores it in a local SQLite FTS5 index kept outside the library. Only books that are not indexed yet are processed; an initial run over a whole library can take several minutes.

Args: book_ids: Optional list of book ids to index; default: all books that are not indexed yet. limit: Optional cap on how many books to index in this call.

Inputs: limit, book_ids. Returns: object

detect_scanned_booksA

Find library books whose PDF has no usable text layer (scanned pages).

Such books stay unsearchable until OCR'd with ocr_book. Requires the ocr extra (pip install 'calibre-mcp[ocr]'); no API key needed.

Args: limit: Maximum number of scanned books to report (1-200).

Inputs: limit. Returns: object

import_inboxA

Import every ebook file in the configured inbox folder into the library.

Requires the CALIBRE_INBOX_DIR environment variable. Successfully added files and duplicates are moved to <inbox>/imported/YYYY-MM/; files that fail to import are moved to <inbox>/failed/ for inspection.

Inputs: no named parameters. Returns: object

library_infoA

Show the active library: its path on disk, number of books, calibre version.

Inputs: no named parameters. Returns: object

list_booksA

Browse books in the library; defaults to most recently added first.

Args: limit: Maximum number of results (1-200, default 20). sort_by: calibre field to sort by, e.g. id, title, authors, timestamp. order: "desc" (default) or "asc". search: Optional calibre search expression to filter the listing.

Inputs: limit, order, search, sort_by. Returns: object

ocr_bookA

OCR a scanned PDF via the configured cloud provider and index the text.

Detection → page rendering → provider transcription → cache → full-text index → (by default) pandoc re-typeset EPUB attached to the book's existing record. Books with a usable text layer are left untouched.

Configuration: CALIBRE_OCR_PROVIDER (default "anthropic"), CALIBRE_OCR_API_KEY, CALIBRE_OCR_MODEL, CALIBRE_OCR_BASE_URL, CALIBRE_OCR_MAX_PAGES.

Args: book_id: Book whose PDF format should be OCR'd. typeset: Also build a re-typeset EPUB with pandoc (default True). import_format: Attach the EPUB to the book record (default True).

Inputs: book_id (required), typeset, import_format. Returns: object

ocr_scanned_booksA

OCR all scanned-PDF books in the library, in resumable batches.

Detects scanned books, skips any that already have OCR output cached, and runs the full ocr_book pipeline (OCR → index → optional re-typeset EPUB) on up to limit remaining books. Repeat the call to work through the whole library; per-batch caching makes interruptions safe.

Args: limit: Maximum books to OCR in this call (1-100, default 10). typeset: Also build re-typeset EPUBs with pandoc (default True). import_format: Attach the EPUBs to book records (default True).

Inputs: limit, typeset, import_format. Returns: object

read_bookA

Read a page of a book's plain text, converted on demand by calibre.

The first call converts the book (a copy in a cache directory — the library is never modified); later calls reuse the cache. Returns the chunk plus next_offset for paging and total_chars for context.

Args: book_id: The book's id (find it with search_books). offset: Character offset to start reading from (0 = beginning). limit: Maximum characters to return (1-40000, default 12000).

Inputs: book_id (required), limit, offset. Returns: object

search_booksA

Search the library with calibre's query language.

Args: query: A calibre search expression, e.g. author:asimov, title:"i robot", tags:python. An empty string matches everything. limit: Maximum number of results (1-200, default 20).

Inputs: query (required), limit. Returns: object

search_in_bookA

Full-text search inside book contents, with match snippets for quoting.

Searches the local text index; books must be indexed first with build_index (a one-time, cached step). Matching is substring-based, so Chinese and English queries both work without word segmentation.

Args: query: Text to find inside book contents. book_id: Optional book id to restrict the search to a single book. limit: Maximum number of matches to return (1-100, default 20).

Inputs: query (required), limit, book_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools target distinct actions: metadata search, browsing, full-text search, reading, and OCR are clearly separated. Minor overlap exists between list_books (which accepts a search filter) and search_books, and between ocr_scanned_books and ocr_book, but descriptions clarify the batch-vs-single distinction.

    Naming Consistency4/5

    The majority of tools follow a clear verb_noun pattern like search_books, add_books, build_index, and read_book. A few deviations stand out: library_info uses noun_info, search_in_book uses a preposition, and ocr_book/ocr_scanned_books use an acronym as the verb, but the overall style remains predictable.

    Tool Count5/5

    Eleven tools is a well-scoped size for a Calibre-focused server covering library browsing, metadata search, book import, reading, full-text search, and OCR. Each tool addresses a distinct workflow without feeling bloated or redundant.

    Completeness4/5

    The toolset covers the core workflows thoroughly: discovering, searching, adding, reading, indexing, and OCR-ing books. Obvious gaps like metadata editing, book deletion, or retrieving original format files are absent, but they appear to be outside the server's intended reading/OCR-oriented scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with research capabilities for local Calibre e-book libraries, including fulltext search across titles, ISBNs, and comments, plus structured excerpt retrieval from books.
      2
      GPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching, reading, and managing a Calibre ebook library through natural language, with features like metadata search, full-text search, content extraction, and library management.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables read-only search, browsing, and metadata retrieval from a local Calibre e-book library using natural language queries.
      MIT