calibre-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@calibre-mcp List the most recently added books in my Calibre library."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 path, number of books, calibre version |
| Full calibre query language search ( |
| Browse the library, defaults to most recently added first |
| Import ebook files or whole directories, with duplicate detection |
| Import everything in the inbox folder and file it away |
| One-time index of book contents for full-text search |
| Search inside book contents, returning match snippets |
| Read a book's plain text page by page (converted on demand) |
| Find books whose PDF is scanned (no text layer) |
| OCR a scanned PDF via a cloud provider, index it, and re-typeset it into an EPUB |
| 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 (recommended)
pipx install calibre-mcpuv
uv tool install calibre-mcppip
pip install calibre-mcpFrom source
git clone https://github.com/ZehuiTIAN/calibre-mcp.git
cd calibre-mcp
pip install -e ".[dev]" # dev extras add pytest + ruffConfiguration
Everything is optional on a normal setup; each value can be pinned with an environment variable.
Variable | Meaning | Default |
| Library directory to use | The library your Calibre GUI uses (most-used library from |
| Path to the |
|
| Drop folder for | Disabled (tool errors if used) |
| Where converted text + search index live | OS temp dir (not persistent across reboots) |
| Seconds before a calibredb call is aborted |
|
| OCR backend ( |
|
| API key for the OCR backend | — (required for |
| Model for the OCR backend | provider default |
| Optional API base URL override (proxies/gateways) | — |
| Page cap per |
|
Registering with Claude Code
claude mcp add calibre-mcp -- calibre-mcpor 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:
Point
CALIBRE_INBOX_DIRat a folder, e.g.~/Downloads/Calibre-Inbox.Download ebooks into that folder.
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:
(Optional) point
CALIBRE_TEXT_CACHE_DIRat a persistent location — the default cache lives in the OS temp directory.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 carrynext_offsetandtotal_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 SDKSet
CALIBRE_OCR_API_KEY(and optionallyCALIBRE_OCR_PROVIDER/CALIBRE_OCR_MODEL/CALIBRE_OCR_BASE_URL).detect_scanned_books()— lists books whose PDF has no usable text layer (no key needed for detection).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 forsearch_in_book/read_book, then typesets a clean EPUB with pandoc and attaches it to the existing book record (replacing any previous EPUB).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_inboxsnapshot 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 toolsadd_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
Scored across 11 tools
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.
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.
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.
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
Related MCP Connectors
AI assistant integration for Leaf — track books, log reading sessions, and manage your library.
Academic literature search, retrieval, and private library management on top of OpenAlex.
The media memory layer for AI agents and their humans. Your AI client can search your collection, add and log what you've finished, update ratings and lists, and find patterns across everything you've read, watched, played, and listened to.
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides 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.2GPL 3.0
- AlicenseBqualityCmaintenanceConnects AI agents to Calibre ebook libraries for searching, reading, and managing digital collections. It supports metadata updates, format conversion, and full-text content searches while providing granular permission controls for library access.725MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables read-only search, browsing, and metadata retrieval from a local Calibre e-book library using natural language queries.MIT