Calibre Library

calibre-library-mcp is a local stdio MCP server that lets AI tools search a self-hosted Calibre library over SSH.

It is designed for a common home-lab setup:

• Calibre or Calibre-Web runs on a remote server.
• The Calibre library directory is mounted into a container, commonly at /books.
• SSH access to the host is available from the machine running the AI tool.
• Calibre full-text search is enabled so book contents can be queried.

No HTTP service or public port is opened by this MCP server. The AI tool starts it locally and it reaches the Calibre host over SSH.

Features

• Search book metadata by title or author.
• List recently added books.
• Inspect details for a Calibre book ID.
• Search indexed full text and return snippets.
• Check Calibre full-text index status.
• Optionally trigger a remote index-maintenance script.

Requirements

• Python 3.11 or newer on the local machine.
• The mcp Python package.
• SSH key access from the local machine to the Calibre host.
• Docker on the Calibre host, if you use the default container-based access pattern.
• A Calibre-Web container or equivalent container that can run Python and read the library files.

The default implementation queries SQLite from inside the configured Calibre-Web container with:

docker exec -i "$CALIBRE_WEB_CONTAINER" python3 ...

Install

Clone the repository:

git clone https://github.com/<owner>/calibre-library-mcp.git
cd calibre-library-mcp

Create a virtual environment and install the package:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Configuration

Set these environment variables in your MCP client configuration:

Variable	Required	Description	Example
CALIBRE_SSH_HOST	yes	Hostname or IP address of the Calibre server.	calibre.example.lan
CALIBRE_SSH_USER	yes	SSH user on the Calibre server.	calibre
CALIBRE_SSH_KEY	no	SSH private key path.	/home/user/.ssh/id_ed25519
CALIBRE_SSH_PORT	no	SSH port. Defaults to 22.	22
CALIBRE_WEB_CONTAINER	no	Container used to query the mounted library. Defaults to calibre-web.	calibre-web
CALIBRE_CONTAINER_BOOKS_PATH	no	Library path inside the container. Defaults to /books.	/books
CALIBRE_REMOTE_LIBRARY_PATH	no	Library path on the remote host for Calibre CLI status checks.	/srv/calibre/library
CALIBRE_DOCKER_IMAGE	no	Calibre image used for calibredb status checks.	lscr.io/linuxserver/calibre:latest
CALIBRE_MAINTENANCE_SCRIPT	no	Optional remote script for refreshing FTS.	/usr/local/bin/calibre-fts-maintenance.sh

MCP Client Config

Most MCP clients accept a stdio server definition similar to this:

{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/calibre-library-mcp",
      "env": {
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre",
        "CALIBRE_SSH_KEY": "/home/user/.ssh/id_ed25519",
        "CALIBRE_WEB_CONTAINER": "calibre-web",
        "CALIBRE_CONTAINER_BOOKS_PATH": "/books",
        "CALIBRE_REMOTE_LIBRARY_PATH": "/srv/calibre/library"
      }
    }
  }
}

If you do not install the package, run it from a checkout:

{
  "mcpServers": {
    "calibre-library": {
      "command": "/absolute/path/to/calibre-library-mcp/.venv/bin/python",
      "args": ["-m", "calibre_library_mcp.server"],
      "cwd": "/absolute/path/to/calibre-library-mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/calibre-library-mcp/src",
        "CALIBRE_SSH_HOST": "calibre.example.lan",
        "CALIBRE_SSH_USER": "calibre"
      }
    }
  }
}

Tools

calibre_search_books

Searches metadata by title or author.

Arguments:

• query: search text.
• limit: maximum results, default 10.

calibre_recent_books

Lists recently added books.

Arguments:

• limit: maximum results, default 10.

calibre_book_details

Returns metadata, formats, tags, and file names for one Calibre book ID.

Arguments:

• book_id: numeric Calibre book ID.

calibre_search_text

Searches extracted full text from Calibre's full-text index.

Arguments:

• query: search text.
• limit: maximum results, default 10.
• snippet_chars: snippet length, default 500.

calibre_index_summary

Returns raw index counts by format.

calibre_index_status

Runs Calibre's own calibredb fts_index status command through Docker on the remote host.

calibre_run_index_maintenance

Starts the optional remote maintenance script configured by CALIBRE_MAINTENANCE_SCRIPT.

Security Notes

• Use a dedicated SSH key with the least permissions practical.
• Do not publish private hostnames, IP addresses, usernames, or keys in MCP config examples.
• Keep the MCP server local to the AI tool. It does not need to listen on a network port.
• The search tools are read-only. The optional maintenance tool can start a remote script, so configure it only if you want that capability.

Calibre Full-Text Search

The calibre_search_text tool depends on Calibre's full-text search index. See docs/calibre-full-text-search.md for setup and maintenance instructions.

Limitations

• Calibre indexes text it can extract from each book file.
• Scanned PDFs need OCR text layers before they become searchable.
• Images, diagrams, and screenshots are not searchable unless OCR has been applied.
• Very large libraries may take a while to search with simple substring matching.