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

Available tools

Tool	Purpose
server_info	Show server, Calibre, cache, and library configuration
library_status	Show book count and full-text indexing status
search_books	Search Calibre metadata
search_fulltext	Search inside indexed ebooks and return snippets
get_book_metadata	Return all available metadata for one book
list_recent_books	List books most recently added
list_categories	Browse authors, tags, series, publishers, and languages
find_related_books	Find books with overlapping authors, series, or tags
clear_cache	Clear the in-memory read cache

MCP resources

URI	Purpose
calibre://library/status	Library and full-text index status
calibre://book/{book_id}	Detailed metadata for a book
calibre://search/{query}	Metadata search results

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

Environment variable	Default	Description
CALIBRE_LIBRARY_PATH	/books	Calibre library inside the container
CALIBREDB	calibredb	Path to the Calibre CLI
CALIBRE_COMMAND_TIMEOUT	120	Command timeout in seconds
CALIBRE_MAX_RESULTS	100	Maximum results returned by a tool
CALIBRE_CACHE_TTL	300	Cache lifetime in seconds; set to 0 to disable
CALIBRE_CACHE_SIZE	256	Maximum cached entries
CALIBRE_CONTENT_SERVER_URL	unset	Optional Content Server base URL
MCP_HOST	0.0.0.0	MCP HTTP bind address
MCP_PORT	8000	MCP port inside the container
HOME	/tmp/calibre-home	Writable location for Calibre 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.

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.