Calibre Library MCP

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.

Related MCP server: calibre-manager

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:

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.