calibre-mcp 
A Model Context Protocol (MCP) server for searching, reading, and managing your Calibre ebook library. Completely rewritten in TypeScript for Bun, it offers ultra-fast performance, deep integration with Calibre's CLI tools, and automated content extraction.
🚀 Features
- Blazing Fast Metadata Search: Queries the Calibre
metadata.dbdirectly via SQLite for near-instant results. - Full-text Content Search: Leverages Calibre's indexed full-text search engine to find specific phrases across your entire library.
- Dynamic Content Extraction: Automatically converts EPUB, PDF, and other formats to text on-the-fly. No manual .txt exports required.
- Comprehensive Library Management: Update database metadata, modify internal file metadata, polish books, and convert between formats.
- Smart Result Distribution: Search results are intelligently balanced across different books to provide diverse matches.
- Custom URL Scheme: Uses
epub://URLs for precise referencing of book locations and line ranges.
📋 Prerequisites
⚙️ Configuration
The server uses the following environment variables:
CALIBRE_LIBRARY_PATH: Path to your Calibre library (wheremetadata.dbresides). Defaults to/Volumes/Xarismata/eBooks/CalibreNuevo.
🛠 Installation
- Clone this repository:
git clone https://github.com/2b3pro/calibre-mcp.git
cd calibre-mcp
- Install dependencies:
bun install
⌨️ Usage
With MCP Inspector
Test the server in an interactive environment:
npx @modelcontextprotocol/inspector bun src/index.ts
With Claude Desktop
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"calibre": {
"command": "bun",
"args": ["run", "/absolute/path/to/calibre-mcp/src/index.ts"]
}
}
}
🧰 Available Tools
| Tool | Description |
|---|---|
search_library | Unified search (metadata + full-text). Supports author:, title:, etc. |
read_content | Extracts text from a book via epub:// URL. Handles dynamic conversion. |
update_metadata | Updates the Calibre database metadata for a book. |
fetch_online_metadata | Retrieves high-quality metadata from online sources (OPF format). |
polish_book | Enhances book files (punctuation, compression, CSS cleanup). |
convert_ebook | Converts books between formats (e.g., EPUB ↔ MOBI) and adds them to the library. |
deep_search_book | Searches for content inside a specific book (bypasses FTS index). |
read_file_metadata | Reads metadata embedded directly inside the ebook file. |
write_file_metadata | Writes metadata directly into the ebook file itself. |
Tool Details & Examples
search_library
Search using natural language for content or specific fields for metadata.
- Query Examples:
"machine learning"(Full-text search)author:Asimov title:Foundation(Metadata search)tag:science-fiction rating:>4(Advanced filtering)
read_content
Uses the epub:// scheme.
- Format:
epub://[author]/[title]@[book_id]#[start_line]:[end_line] - Example:
epub://Isaac%20Asimov/Foundation@123#500:600retrieves lines 500 to 600.
polish_book
Perfect for cleaning up automated conversions or old files.
- Options:
smartenPunctuation,compressImages,upgradeBook,removeUnusedCss.
convert_ebook
Convert formats and automatically update your library record.
- Example:
book_id: 45, output_format: "azw3", options: ["--enable-heuristics"]
deep_search_book
Search directly inside a specific book (useful if Calibre FTS hasn't indexed it yet).
- Example:
book_id: 123, query: "quantum entanglement", context_lines: 3
⚖️ License
Apache License 2.0 - See LICENSE file for details.