Calibre MCP

A read-only Model Context Protocol server for an existing Calibre ebook library.

Calibre MCP lets MCP-compatible clients search book metadata, query Calibre's full-text index, inspect book details, browse library categories, and discover related books. It uses Calibre's supported calibredb command-line interface rather than reading metadata.db directly.

Features

• Metadata search using Calibre's search language

• Full-text search with matching snippets

• Detailed metadata for individual books

• Recently added books

• Authors, tags, series, publishers, and language categories

• Related-book discovery

• MCP resources for books, searches, and library status

• Optional Calibre Content Server links

• In-memory TTL cache

• Streamable HTTP transport

• Podman Quadlet deployment

• No metadata-changing MCP tools

Related MCP server: calibre-manager

Available tools

MCP resources

Requirements

• A Calibre library with metadata.db

• Calibre 9.x

• Python 3.11 or newer

• An MCP client supporting Streamable HTTP

• Podman and systemd for the included Quadlet deployment

The full-text tools require Calibre's full-text index to be enabled and completed.

Quick start with Podman Quadlet

1. Clone the repository

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

2. Confirm your Calibre library

The supplied Quadlet assumes:

/tank/media/Books

Confirm that the library database exists:

test -f /tank/media/Books/metadata.db && echo "Calibre library found"

3. Determine the library owner

stat -c 'uid=%u gid=%g owner=%U:%G' /tank/media/Books

Edit quadlet/calibre-mcp.container and set User= to the returned numeric UID and GID:

User=1000:1000

Also change the host library path if yours is different:

Volume=/tank/media/Books:/books

4. Build the image

sudo podman build \
  --build-arg CALIBRE_VERSION=9.11.0 \
  -t localhost/calibre-mcp:1.0.0 .

5. Install the Quadlet

sudo mkdir -p /etc/containers/systemd

sudo cp quadlet/calibre-mcp.container \
  /etc/containers/systemd/calibre-mcp.container

sudo systemctl daemon-reload
sudo systemctl start calibre-mcp.service

Do not run systemctl enable calibre-mcp.service. The generated service is transient; the Quadlet's [Install] section creates the boot dependency.

6. Verify the deployment

sudo systemctl status calibre-mcp.service --no-pager
sudo journalctl -u calibre-mcp.service -n 100 --no-pager
sudo podman ps --filter name=calibre-mcp

Verify Calibre inside the container:

sudo podman exec calibre-mcp \
  calibredb list \
  --with-library /books \
  --for-machine \
  --fields title \
  --limit 1

sudo podman exec calibre-mcp \
  calibredb fts_index status \
  --with-library /books

The default endpoint is:

http://localhost:8008/mcp

Test with MCP Inspector

npx @modelcontextprotocol/inspector

Select Streamable HTTP and connect to:

http://YOUR_SERVER:8008/mcp

Example metadata search:

{
  "query": "author:asimov",
  "limit": 10
}

Example full-text search:

{
  "query": "zero trust architecture",
  "limit": 10
}

Example restricted full-text search:

{
  "query": "encryption",
  "limit": 10,
  "restrict_to": "search:tags:security"
}

Connect an MCP client

Use the Streamable HTTP endpoint exposed by the server:

http://YOUR_SERVER:8008/mcp

Client configuration formats vary. Consult your client's MCP documentation and select Streamable HTTP rather than stdio or legacy SSE.

Calibre search examples

search_books accepts Calibre search expressions:

author:asimov
title:"i robot"
tags:history
series:"Discworld"
publisher:penguin
languages:eng
rating:>=4

An empty query returns all books, subject to the result limit.

Optional Content Server links

Set the URL of your existing Calibre Content Server in the Quadlet:

Environment=CALIBRE_CONTENT_SERVER_URL=http://mini-nas:8083

When configured, metadata results include browser and format-download links.

Configuration

Why the library mount is writable

Calibre checks whether the library filesystem is case-sensitive by briefly creating and deleting a probe file in the library root. Consequently, the bind mount cannot be mounted read-only.

This server remains functionally read-only because it exposes no tools that call Calibre commands such as:

• add

• remove

• set_metadata

• add_format

• remove_format

Run the container as the same unprivileged UID and GID that owns the library. Do not run it as root unless your environment specifically requires that.

Security

• Keep port 8008 restricted to trusted LAN or Tailscale clients.

• Do not expose the endpoint directly to the public Internet.

• Streamable HTTP does not add authentication in this deployment.

• Place an authenticated reverse proxy in front of the service before broader exposure.

• Pin release versions rather than using a moving container tag.

• Review SECURITY.md before reporting a vulnerability.

Red-team hardening (round 1)

Ten adversarial attack vectors were proven with failing tests and then fixed. Each TestAttack_* test in tests/attack_round1_test.py is a permanent regression fixture for its vector.

Known-safe surfaces verified in this round: shell injection (list argv, no shell=True), option-value injection (--sort-by/--categories/--restrict-to reject leading-dash values in Calibre's parser), resource URI path traversal (non-numeric ids rejected), result-limit clamping (_limit), and cache race conditions (lock-guarded).

Red-team hardening (round 2)

Six input-shape validation vectors proven and fixed; fixtures in tests/attack_round2_test.py.

Red-team hardening (round 3)

Three error-path robustness vectors proven and fixed; fixtures in tests/attack_round3_test.py.

Red-team hardening (round 4)

Two concurrency/process-flood vectors proven and fixed; fixtures in tests/attack_round4_test.py.

Red-team hardening (round 5 — terminal verification)

Zero new vulnerabilities. A coverage-gap audit added 11 verification tests (tests/attack_round5_test.py) exercising every entry point not yet covered by rounds 1–4 — search_resource, book_resource (non-numeric, traversal-like, in-range), status_resource, library_status, list_recent_books, clear_cache, search_fulltext list payloads, zero/negative limits, TTL-zero cache disable, and whitespace queries. All passed immediately, confirming the rounds 1–4 defences hold across the full tool/resource surface.

Two deployment-posture documentation findings were recorded in SECURITY.md (no code change): the Containerfile has no USER directive (runs as root when built outside the Quadlet, which sets User=1000:1000), and the Quadlet sets SecurityLabelDisable=true (SELinux label separation is off).

Local development

Create a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest ruff

Run the tests:

pytest

Run lint checks:

ruff check .

Start the server locally:

export CALIBRE_LIBRARY_PATH="/path/to/Calibre Library"
python server.py

Project status

Version 1.0.0 is suitable for personal and trusted-network deployments. The public API may gain additional tools and resources in future minor releases, while existing tool names and argument shapes will be kept stable where practical.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Licence

Released under the MIT Licence.