calibre-mcp

Локальный MCP-сервер (stdio), который позволяет LLM-хосту — Claude Desktop, Claude Code или любому MCP-совместимому клиенту — управлять библиотекой электронных книг Calibre в диалоговом режиме: поиск, редактирование метаданных, добавление, конвертация, дедупликация, удаление и отправка книг по электронной почте — всё с безопасностью, предполагающей участие человека.

Большинство MCP-серверов для Calibre доступны только для чтения — они ищут и перечисляют. Этот пишет — и делает это безопасно. Редактирование метаданных, добавление, конвертация и удаление книг — это те операции, где инструмент может реально повредить или потерять вашу библиотеку, поэтому каждое изменение здесь проходит через архитектуру, созданную так, чтобы сделать это невозможным по случайности:

• План → подтверждение для каждого разрушительного действия. Первый вызов возвращает читаемое человеком описание изменений и confirmation_token; ничего не меняется, пока вы не вызовете повторно с этим точным токеном.

• Автоматическое резервное копирование metadata.db перед каждой записью (скользящее, последние 20).

• Восстановимые удаления — копия в корзину и корзина Calibre, никогда не жёсткое удаление.

• Чтение не может ничего повредить — SQLite-соединение открывается в режиме mode=ro.

Создан, чтобы перестать кликать по интерфейсу Calibre и управлять библиотекой из чата — и намеренно спроектирован как демонстрация того, как создать инструмент, которому разрешено удалять файлы пользователя: гибридный дизайн ввода-вывода, явная таксономия ошибок, шлюзы одобрения человеком для каждого разрушительного действия и набор тестов, который никогда не касается реальных пользовательских данных. См. PRODUCT.md о том, что он делает и почему, и ARCHITECTURE.md для полного описания дизайна.

Почему гибридный дизайн

• Чтение (search, list, view, поиск дубликатов) обращается к metadata.db напрямую, только для чтения — быстро и структурно неспособно повредить библиотеку (SQLite-соединение открывается в режиме mode=ro).

• Запись (edit, add, remove, convert, email) выполняется через собственные CLI-инструменты Calibre (calibredb, ebook-convert, calibre-smtp) — никогда не через сырой SQL, — поэтому Calibre остаётся авторитетом для своей собственной базы данных.

• Каждой записи предшествует автоматическое резервное копирование metadata.db (скользящее, хранит последние 20).

• Удаление обратимо: файлы копируются в управляемую папку корзины и книга отправляется в корзину Calibre — никогда не постоянное удаление.

• Каждый изменяющий или внешний инструмент является двухэтапным (план → подтверждение): первый вызов возвращает читаемое человеком описание плюс confirmation_token; ничего не меняется — и ничего не отправляется — пока вы не вызовете повторно с этим точным токеном.

Полное обоснование, границы модулей и журнал решений, стоящих за этими выборами, находятся в ARCHITECTURE.md.

Related MCP server: calibre-manager

Требования

• Calibre установлен, с calibredb и ebook-convert в вашем PATH (calibredb --version). calibre-smtp также требуется, если вы хотите использовать email_book.

• Python ≥ 3.12 и uv.

Установка

Без клонирования (рекомендуется) — uv собирает и запускает его прямо из репозитория, без ручного клонирования:

uvx --from git+https://github.com/gustavofsousa/calibre-mcp calibre-mcp

Из локального клона (для разработки или для фиксации конкретного состояния):

git clone https://github.com/gustavofsousa/calibre-mcp calibre-mcp
cd calibre-mcp
uv sync

Настройка

Сервер управляет одной библиотекой, задаваемой через переменную окружения:

Сервер быстро завершается при запуске с понятной ошибкой, если CALIBRE_LIBRARY_PATH не задан или в каталоге нет metadata.db.

email_book дополнительно требует учётные данные SMTP-релея (загружаются лениво — сервер запускается нормально без них, и только email_book завершится ошибкой, если они отсутствуют):

Claude Desktop / Claude Code

Добавьте в ваш MCP-конфиг (например, claude_desktop_config.json). Без клонирования — запускается прямо из репозитория через uvx:

{
  "mcpServers": {
    "calibre": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gustavofsousa/calibre-mcp", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

Или из локального клона:

{
  "mcpServers": {
    "calibre": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/calibre-mcp", "run", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

Запуск вручную

CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run calibre-mcp
# or equivalently:
CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run python -m calibre_mcp

Сервер общается через stdio (JSON-RPC); он ничего не выводит в stdout, кроме MCP-кадрирования — все логи идут в stderr, намеренно (см. ARCHITECTURE.md).

Инструменты

Плюс один MCP-ресурс, calibre://library/stats — агрегированный профиль библиотеки (итоги, смесь форматов/языков, полнота метаданных, флаги качества данных), читаемый без вызова инструментов.

Полный контракт каждого инструмента (крайние случаи, условия ошибок, точный список разрешённых полей) документирован в его docstring в server.py — эти docstring — то, что видит LLM-хост, поэтому они также служат справочником по API.

Разработка

uv run ruff check src tests   # lint
uv run pytest                 # full suite (unit + integration + e2e)
uv run pytest -m unit         # fast unit tests only

137 тестов в трёх уровнях (unit, integration, e2e); тесты записи никогда не касаются реальной библиотеки — см. ARCHITECTURE.md.

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

src/calibre_mcp/
├── server.py               # FastMCP tool surface — the only stdio/MCP-aware module
├── library.py               # CalibreLibrary facade — orchestrates every tool's business logic
├── sqlite_reader.py         # Read-only metadata.db access (the only sqlite3 call site)
├── calibredb_runner.py      # calibredb subprocess wrapper (search/edit/add/remove/add_format)
├── ebook_convert_runner.py  # ebook-convert subprocess wrapper
├── calibre_smtp_runner.py   # calibre-smtp subprocess wrapper
├── backup.py                 # metadata.db snapshots + recoverable trash
├── confirmation.py           # plan→confirm token derivation/verification
├── config.py                  # env-driven startup config, fail-fast validation
└── errors.py                  # the failure taxonomy every layer maps to

Дорожная карта

Реализовано: полный цикл чтения/курирования/распространения (поиск, список, просмотр, редактирование, добавление, удаление, конвертация, дедупликация, email). Что дальше — самопознание библиотеки, массовые операции, обогащение обложек/метаданных, синхронизация устройств — отслеживается в .specs/ROADMAP.md, включая обоснование последовательности и что явно вне области действия.

Вклад

См. CONTRIBUTING.md для рабочего процесса разработки, инвариантов, которые должен сохранять PR, и как работает процесс, управляемый спецификациями, лежащий в основе этого репозитория.

Лицензия

MIT © Gustavo F Sousa.