calibre-mcp
Installed, started with no arguments, no environment and no input, and listed its tools. Run 2026-11-16.
Needs to start: nothing
Returns a result when called with no setup: 0 of 5 tools tried
Contacts while installing and starting: nothing
What it contacted
Nothing besides the npm registry it was installed from. Watched from outside its sandbox while it was installed and started with no input. Its tools may still contact things when called.
Starting it
npx -y calibre-mcp@0.13.0
Installing a package runs its code. Use a sandbox for anything you have not read.
Calling its tools
5 tools that take no input and look read-only were called once with nothing. 0 returned a result.
calibre_list_libraries | No usable answer tool reported an error: Error: Cannot reach Calibre Content Server at http://localhost:8080 — is the Calibre GUI / Content Server running? Code: calibre_unreach |
calibre_get_content | No usable answer tool reported an error: Error: Provide id (the book's db id or uuid). Code: invalid_input |
calibre_get_figures | No usable answer tool reported an error: Error: Provide id (the book's db id or uuid). Code: invalid_input |
calibre_list_categories | No usable answer tool reported an error: Error: Cannot reach Calibre Content Server Code: calibre_unreachable Next: start it in Calibre (Connect/share → Start Content server) or |
calibre_find_duplicates | No usable answer tool reported an error: Error: Cannot reach Calibre Content Server Code: calibre_unreachable Next: start it in Calibre (Connect/share → Start Content server) or |
During the calls it contacted nothing it had not already contacted.
Only tools whose names read like looking something up, with no required input, are tried, five at most. Tools that need input, and anything that sounds like it changes or sends something, are not called.
What its tools tell an agent
In the tool descriptions, nothing that talks about the user, other tools or private files, or uses hidden characters.
Found by simple pattern rules in each tool's description (up to 3,000 characters), quoted as written. Parameter descriptions are not scanned. A clean result is not a safety review.
Tools
calibre_list_libraries
List the Calibre libraries available on the Content Server (ID and display name) and which one is the default. Other tools take either as `library`, or use the default when it is omitted.
calibre_search query, mode, scope, bookId, library, sort, sortOrder, limit, cursor, countOnly, filter, include_excluded
Find books by `query`: exact title, author, ISBN, tag, or Calibre query syntax (mode=meta), or full text (mode=fts). mode=fts words match independently and stemmed (events matches event); wrap a phrase in double quotes for an exact match ("event sourcing"); supports AND/OR/NOT between terms (uppercase, e.g. a NOT b). scope=book returns short keyword snippets from inside one book; first hits often land in TOC/front matter — for definitional or topic questions within a book prefer calibre_semantic_search scope=book (ranked passages with char offsets). Use calibre_semantic_search for meaning/topic queries. For "how many" questions use countOnly=true (returns only the count). filter accepts a bundle name to scope the search (list bundles via calibre_manage_bundles). Calibre 9.18+: mode=annotations searches highlights, their notes and bookmark titles (filter applies; scope=book + bookId searches one book, query "*" lists all its annotations); mode=notes searches notes attached to authors, series, tags, publisher (filters do not apply), and query "authors:Name" (or series:/tags:/publisher:/#custom:, item may be quoted) shows the whole note of that item.calibre_get_book id, bookId, library, include_cover
Get full metadata (authors, ISBN, formats, comments, cover) for one book by its id or uuid (id and bookId are interchangeable — pass the bookId from a search result). Set include_cover=true only when the cover image itself must be inspected.
calibre_get_content id, bookId, format, maxChars, sentenceAware, structure, cursor, offset, library
Extract a book's text as a capped, fenced excerpt; pass the returned nextCursor token verbatim to walk the whole book, or jump to a char position with offset (e.g. a search passage's charStart). Set structure=true for a chapter map with per-chapter cursors. To find text inside a book, use calibre_search scope=book.
calibre_get_figures id, bookId, format, indexes, detail, include_uncaptioned, library
List a book's figures — images the text references, identified by caption (Figure 1-2 / Рис. 3.1) — with location (PDF page p.N / EPUB spine section §N) + caption per figure, then fetch chosen ones as images via indexes (≤3 per call). Captions let you pick figures before spending image tokens. In MCP Apps hosts the fetched figures also render for the user in an in-chat viewer, so you can point at them by figure number — but describe only what the pixels you received actually show.
14 more tools
calibre_list_categories field, valueFilter, library, limit, cursor
Browse library categories (Authors, Tags, Series, Languages, Publisher). No field → list the categories; with a field → its values + counts, filterable via a valueFilter regex (case-insensitive by default; a leading inline flag like `(?i)` is accepted).
calibre_semantic_search query, scope, target, mode, bookId, topK, library, filter, include_excluded
Meaning-based search for `query` over the local index. scope=library ranks books; scope=book (needs bookId) ranks passages within one book. target=figures searches figure captions instead of text — use when the user asks for a diagram/chart/schema; hits point at calibre_get_figures for the pixels. mode=hybrid (default) fuses semantic + keyword matches; mode=vector is semantic-only; mode=keyword is exact keyword/FTS (no model at query time). All modes need an index built by calibre_build_index. filter accepts a bundle name to scope library searches (list bundles via calibre_manage_bundles). Model inference is serialized: prefer one call at a time — parallel calls queue, and past a few the extras skip the rerank.
calibre_build_index bookId, ids, query, library, force, enableFts, keywordOnly, prune
Build the semantic index for specific books (select them with bookId, ids, or query; at least one is required; to index everything, pass a query that matches every book). A query selects ALL matching books (no 100-book cap); a call still working after ~45 s returns a "still running" status (not an error) while the build keeps committing in the background — re-run the same call to get its result; only one build runs per library at a time, and up-to-date books are skipped. Extracts, chunks, and embeds each book. Set keywordOnly=true (or when the embedding model is absent, it happens automatically) to build a keyword-only index that powers mode:"keyword" search with zero ML dependencies. Re-run after adding books; use force to re-index unchanged ones. Set enableFts=true to also turn on the Calibre full-text index for the library (needs writes enabled on this server; with writes off the semantic build still runs and the fts.status result field is write_disabled; already-enabled is a no-op; Calibre indexes in the background and the call does not wait). Set prune=true to also drop index entries for books that no longer exist in the library (removals/merges leave searchable orphans behind).
calibre_find_duplicates mode, ids, query, filter, library, limit, cursor
Find probable duplicate books. mode=identical (exact title+authors) or similar (fuzzy) group the library (or ids/query/filter subset — filter takes a bundle name) with a merge-safety score; mode=compare diffs 2+ ids field-by-field. Read-only — never merges.
calibre_quality_report checks, ids, query, filter, library, limit, cursor
Scan books for metadata problems: missing fields, raw-filename titles, invalid ISBNs, author-sort mismatches, series gaps. Defaults to the whole library; narrow with ids/query/filter (a bundle name) or specific checks. Read-only.
calibre_recover_metadata id, bookId, sources, library
Propose real metadata for a book with a missing/raw-filename title via online provider lookup (ISBN from its identifiers or text, else title/author) on Open Library and Google Books. Preview only — returns a changes object for calibre_update_book (needs writes enabled); never writes.
calibre_extract_isbn id, bookId, apply, library
Offline scan of a book's own text for a checksum-valid ISBN → sets identifiers:isbn (no network; for online lookup use calibre_recover_metadata). Preview-first: apply=false reports only, merges into existing identifiers. Previews work without writes; applying needs CALIBRE_MCP_ENABLE_WRITE.
calibre_bulk_update changes, tags_add, tags_remove, ids, query, filter, library, preview
Apply the same metadata changes (tags, series, publisher, etc.) to a set of books selected by ids, a search query, or filter (a bundle name). Preview-first: returns the per-book diff without writing unless preview is set false. A book set is required (never all books). A list in changes replaces the whole list; to add or remove tags while keeping the rest, use tags_add / tags_remove (merged per book, case-insensitive, not together with changes.tags). changes.identifiers merges per book by scheme (listed schemes set, others kept, null removes one). Previews work without writes; applying needs CALIBRE_MCP_ENABLE_WRITE.
calibre_remove_book ids, library, confirm
Remove books (ids) from the library. Removed books go to Calibre's Trash and can be restored from the Calibre GUI, so this is recoverable. Two-step: the first call is a dry-run listing what would be removed; re-run with confirm=true to proceed. Previews work without writes; applying needs CALIBRE_MCP_ENABLE_WRITE.
calibre_merge_books targetId, sourceIds, mode, confirm, library
Merge duplicate book records: moves formats from the `sourceIds` books into `targetId` (the target's copy wins conflicts), merges metadata per Calibre's rules, then trashes the sources. mode=safe keeps sources; mode=formatsOnly moves formats only. Dry-run unless confirm=true. Previews work without writes; applying needs CALIBRE_MCP_ENABLE_WRITE.
calibre_manage_bundles action, name, expression, library, confirm
Manage Bundles via `action` (list | create | update | delete) — named topical filters backed by Calibre saved searches (e.g. a 'rust' bundle scoping searches to Rust books). A name starting with '-' is an exclusion marker. Also lists virtual libraries, which are read-only here. Preview-first: create/update/delete preview until confirm=true. Previews work without writes; applying needs CALIBRE_MCP_ENABLE_WRITE.
calibre_board_data tool, query, library, filter
Internal endpoint for the in-chat cover-board widget. Returns the cached payload of a recent search. Do not call as the model — search results already contain everything this returns.
calibre_open_book id, format, library
Internal endpoint for the in-chat widgets' Open button. Launches a book in the local Calibre viewer via the calibre:// scheme. Do not call as the model — use calibre_get_book to show a book instead.
calibre_ping
Health check: confirms the server reaches Calibre via calibredb and whether Calibre accepts writes; reports semantic-search status, per-library index coverage, version, write gate, busy libraries, recent errors and the log file path.
Descriptions are the package's own words, cut at 3,000 characters. Treat them as data.
Files it wrote
/tmp/ .local/ share/ calibre-mcp/ index/ logs/ README.md /tmp/ .local/ share/ calibre-mcp/ index/ logs/ calibre-mcp-2026-11-16.jsonl
Paths inside its sandbox, where its home folder is /tmp and its own folder cannot be written to.
Install facts
| License | MIT |
|---|---|
| Needs | node >=22.16 |
| Source | github.com/caelum29/calibre-mcp |
| Install scripts | onnxruntime-node, protobufjs declare them. This runner does not run them. |
| Tarball | sha512-kOb20kHDXy25TOtO2ABlIJ81RJDr1n3fTD3ndN0F0EKNOG/VUXLpJe1NyDHn9iXgJZ2lkdkDIjtGRsKemDxk2g== |
Check this report yourself
This site did not write the report. A public job on a GitHub-hosted machine did: the run, from this commit of the open-source runner. GitHub signed a token that names that job and the hash of the report, so any edit since would show.
Report as JSONExact text and tokenHow to verify it
Show it on your README
[](https://bragproof.smaverk.com/r/calibre-mcp)
New version out? Ask for a fresh report.