Calibre MCP

Сервер Model Context Protocol только для чтения для существующей библиотеки электронных книг Calibre.

Calibre MCP позволяет MCP-совместимым клиентам искать метаданные книг, запрашивать полнотекстовый индекс Calibre, просматривать сведения о книгах, обозревать категории библиотеки и находить связанные книги. Он использует поддерживаемый интерфейс командной строки calibredb вместо прямого чтения metadata.db.

Возможности

• Поиск по метаданным с использованием языка поиска Calibre

• Полнотекстовый поиск с соответствующими фрагментами

• Подробные метаданные для отдельных книг

• Недавно добавленные книги

• Авторы, теги, серии, издатели и языковые категории

• Обнаружение связанных книг

• Ресурсы MCP для книг, поисковых запросов и статуса библиотеки

• Необязательные ссылки на Calibre Content Server

• Кэш TTL в памяти

• Транспорт Streamable HTTP

• Развёртывание Podman Quadlet

• Нет инструментов MCP, изменяющих метаданные

Related MCP server: calibre-manager

Доступные инструменты

Ресурсы MCP

Требования

• Библиотека Calibre с metadata.db

• Calibre 9.x

• Python 3.11 или новее

• MCP-клиент, поддерживающий Streamable HTTP

• Podman и systemd для включённого развёртывания Quadlet

Инструменты полнотекстового поиска требуют, чтобы полнотекстовый индекс Calibre был включён и построен.

Быстрый старт с Podman Quadlet

1. Клонируйте репозиторий

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

2. Проверьте вашу библиотеку Calibre

Поставляемый Quadlet предполагает:

/tank/media/Books

Убедитесь, что база данных библиотеки существует:

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

3. Определите владельца библиотеки

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

Отредактируйте quadlet/calibre-mcp.container и установите User= в возвращённые числовые UID и GID:

User=1000:1000

Также измените путь к библиотеке на хосте, если он у вас другой:

Volume=/tank/media/Books:/books

4. Соберите образ

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

5. Установите 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

Не запускайте systemctl enable calibre-mcp.service. Сгенерированный сервис является временным; раздел [Install] в Quadlet создаёт зависимость при загрузке.

6. Проверьте развёртывание

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

Проверьте Calibre внутри контейнера:

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

Конечная точка по умолчанию:

http://localhost:8008/mcp

Тестирование с MCP Inspector

npx @modelcontextprotocol/inspector

Выберите Streamable HTTP и подключитесь к:

http://YOUR_SERVER:8008/mcp

Пример поиска по метаданным:

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

Пример полнотекстового поиска:

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

Пример ограниченного полнотекстового поиска:

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

Подключение MCP-клиента

Используйте конечную точку Streamable HTTP, предоставляемую сервером:

http://YOUR_SERVER:8008/mcp

Форматы конфигурации клиентов различаются. Обратитесь к документации MCP вашего клиента и выберите Streamable HTTP, а не stdio или устаревший SSE.

Примеры поиска Calibre

search_books принимает выражения поиска Calibre:

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

Пустой запрос возвращает все книги с учётом ограничения на количество результатов.

Необязательные ссылки Content Server

Укажите URL вашего существующего Calibre Content Server в Quadlet:

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

При настройке результаты метаданных включают ссылки для просмотра и загрузки форматов.

Конфигурация

Почему точка монтирования библиотеки доступна для записи

Calibre проверяет, чувствительна ли файловая система библиотеки к регистру символов, кратковременно создавая и удаляя пробный файл в корне библиотеки. Следовательно, bind-монтирование не может быть смонтировано в режиме только для чтения.

Этот сервер остаётся функционально доступным только для чтения, поскольку он не предоставляет инструментов, вызывающих такие команды Calibre, как:

• add

• remove

• set_metadata

• add_format

• remove_format

Запускайте контейнер от того же непривилегированного UID и GID, которым принадлежит библиотека. Не запускайте его от root, если ваше окружение специально этого не требует.

Безопасность

• Держите порт 8008 ограниченным для доверенных клиентов LAN или Tailscale.

• Не открывайте конечную точку напрямую в публичный Интернет.

• Streamable HTTP не добавляет аутентификацию в этом развёртывании.

• Поместите аутентифицирующий обратный прокси перед сервисом перед более широким доступом.

• Закрепляйте версии релизов, а не используйте плавающий тег контейнера.

• Изучите SECURITY.md перед сообщением об уязвимости.

Усиление red-team (раунд 1)

Десять векторов атак со стороны злоумышленника были подтверждены падающими тестами, а затем исправлены. Каждый тест TestAttack_* в tests/attack_round1_test.py является постоянным регрессионным тестом для своего вектора.

Известные безопасные поверхности, проверенные в этом раунде: инъекция команд оболочки (список argv, без shell=True), инъекция значений параметров (--sort-by/--categories/--restrict-to отклоняют значения с ведущим дефисом в парсере Calibre), обход пути в URI ресурсов (нечисловые идентификаторы отклоняются), ограничение количества результатов (_limit) и состояния гонки в кэше (защищены блокировкой).

Усиление red-team (раунд 2)

Шесть векторов проверки формы входных данных подтверждены и исправлены; фикстуры в tests/attack_round2_test.py.

Усиление защиты от Red-team (раунд 3)

Три вектора надёжности обработки ошибок подтверждены и исправлены; фикстуры в tests/attack_round3_test.py.

Усиление защиты от Red-team (раунд 4)

Два вектора, связанных с параллелизмом и флудом процессов, подтверждены и исправлены; фикстуры в tests/attack_round4_test.py.

Усиление защиты от Red-team (раунд 5 — финальная проверка)

Ноль новых уязвимостей. Аудит пробелов в покрытии добавил 11 проверочных тестов (tests/attack_round5_test.py), охватывающих каждую точку входа, ещё не покрытую раундами 1–4: search_resource, book_resource (нечисловые, похожие на обход каталога, в допустимом диапазоне), status_resource, library_status, list_recent_books, clear_cache, search_fulltext с полезными нагрузками в виде списков, нулевые/отрицательные лимиты, отключение кэша при TTL=0 и запросы из пробелов. Все тесты прошли сразу, подтвердив, что защиты раундов 1–4 действуют на всей поверхности инструментов/ресурсов.

Два замечания к документации о развёртывании зафиксированы в SECURITY.md (без изменения кода): в Containerfile отсутствует директива USER (при сборке вне Quadlet контейнер запускается от root, тогда как Quadlet задаёт User=1000:1000), а Quadlet устанавливает SecurityLabelDisable=true (разделение меток SELinux отключено).

Локальная разработка

Создайте виртуальное окружение:

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

Запустите тесты:

pytest

Запустите lint-проверки:

ruff check .

Запустите сервер локально:

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

Статус проекта

Версия 1.0.0 подходит для личного использования и развёртывания в доверенных сетях. Публичный API может пополняться дополнительными инструментами и ресурсами в будущих минорных релизах, при этом существующие имена инструментов и формы аргументов будут сохраняться стабильными, где это практически возможно.

Участие в разработке

Приветствуются issues и pull request'ы. См. CONTRIBUTING.md.

Лицензия

Распространяется под лицензией MIT.