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.db directly 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

• Calibre installed at /Applications/calibre.app (macOS).

• Bun runtime installed.

• A Calibre library.

⚙️ Configuration

The server uses the following environment variables:

• CALIBRE_LIBRARY_PATH: Path to your Calibre library (where metadata.db resides). Defaults to /Volumes/Xarismata/eBooks/CalibreNuevo.

🛠 Installation

1. Clone this repository:

git clone https://github.com/2b3pro/calibre-mcp.git
cd calibre-mcp

2. 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 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:600 retrieves 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.