Calibre Library

Read-only MCP server exposing a local Calibre library (search, details, FTS, samples)

python

2

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pshap-mcp-neolibrarian": {
      "command": "./.venv/Scripts/python.exe",
      "args": [
        "calibre_mcp_server.py"
      ],
      "env": {
        "CALIBRE_CONFIG_PATH": "path/to/config.json"
      }
    }
  }
}

You expose a read‑only interface to your local Calibre library via a lightweight MCP server. This lets you search metadata, inspect book details and formats, run full‑text searches when available, and fetch small content samples for analysis from MCP‑compatible hosts without modifying your library.

How to use

You connect to the MCP server from an MCP client (such as Claude Desktop) to perform read‑only operations on your Calibre library. Typical use cases include searching by author or title, viewing per‑book details and available formats, running quick health checks, and pulling small content samples for analysis. All actions are read‑only and do not alter your library.

How to install

Prerequisites you need before installing the server:

Python 3.12 or newer (3.13 is supported)
Calibre installed locally (calibre‑debug.exe should be accessible)
Access to your Calibre library directory (the folder that contains metadata.db)

Steps to install and set up the MCP server on Windows PowerShell:

# From the project root
python -m venv .venv
./.venv/Scripts/Activate.ps1
pip install -r requirements.txt

Configuration details

Prepare a JSON configuration file with at least these keys. You will point the server to your Calibre library and the Calibre installation path.

{
	"calibre_library_path": "C:/Path/To/Calibre Library",
	"calibre_installation_path": "C:/Program Files/Calibre2"
}

Running the MCP server

The server runs as a local stdio process for MCP hosts. Start it using the Python interpreter from your virtual environment and pass the main server script.

./.venv/Scripts/python.exe calibre_mcp_server.py

Configuring optional environment placeholder

If you want to supply a configuration path at runtime for ease of deployment on MCP hosts, you can use an environment variable.

set CALIBRE_CONFIG_PATH=path/to/config.json

Available tools

ping

Health check that confirms the server is running and exposes accessible paths.

get_total_books

Return the total number of books in the configured Calibre library.

search_by_author

Search books by author name and return matching results.

search_by_title

Search books by title and return matching results.

unified_search

Perform a combined search across author, title, series, formats, and date range with pagination and sorting.

get_book_details

Fetch per‑book details for a given book ID.

get_book_formats

List available formats for a given book.

get_book_sample

Retrieve small content samples for a given book and sample type.

analyze_book_content

Analyze the content of a book with a specified analysis type and maximum length.

full_text_search

Execute a full‑text search across the library with optional case sensitivity and context.

full_text_search_book

Run full‑text search scoped to a single book.

get_books_batch

Fetch details for a batch of books by their IDs.

get_random_books

Retrieve a random selection of books, optionally filtered by formats or series only.

get_full_text_search_stats

Provide statistics about the full‑text search index and usage.