calibreweb-mcp

Сервер Model Context Protocol только для чтения для Calibre-Web (и Calibre-Web Automated), самостоятельно размещаемого веб-интерфейса библиотеки электронных книг.

У Calibre-Web нет REST API — единственным стабильным машиночитаемым интерфейсом является канал каталога OPDS, который он предоставляет для приложений для чтения электронных книг. Этот сервер работает с этим каналом: Atom XML с HTTP Basic авторизацией на входе, структурированные данные о книгах на выходе. Поиск по библиотеке, просмотр курируемых представлений и полок, переход по ссылкам для скачивания в разных форматах и получение обложек прямо в диалог. Он никогда ничего не записывает: каждый инструмент — это GET-запрос к маршрутам OPDS.

📖 Полная документация: calibreweb-mcp.ni-c.de

Требования

• Node.js 22 или новее

• Экземпляр Calibre-Web (разрабатывался с текущим образом linuxserver/calibre-web; Calibre-Web Automated работает так же)

• Пользователь Calibre-Web для сервера. OPDS-канал аутентифицируется с помощью обычного веб-входа — используйте выделенную учётную запись только с ролями «Просмотр» и «Скачивание», а не свою учётную запись администратора. Если экземпляр разрешает анонимный просмотр, сервер может работать и без учётных данных.

Related MCP server: access-calibre

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

¹ Оставьте оба незаданными для экземпляра, разрешающего анонимный просмотр; задание только одного из них является ошибкой конфигурации.

Claude Code

claude mcp add calibreweb \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  -- npx calibreweb-mcp

Claude Desktop

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["calibreweb-mcp"],
      "env": {
        "CALIBRE_WEB_URL": "https://books.example.com",
        "CALIBRE_WEB_USERNAME": "reader",
        "CALIBRE_WEB_PASSWORD": "..."
      }
    }
  }
}

Codex

[mcp_servers.calibreweb]
command = "npx"
args = ["calibreweb-mcp"]
env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }

Инструменты

Все инструменты доступны только для чтения (readOnlyHint: true).

Записи книг включают авторов, теги, серии (с индексом), рейтинг, ограниченное краткое описание, URL обложки и URL для скачивания в каждом формате — готовые ссылки, которые человек может открыть, поскольку у самой модели нет причин скачивать EPUB.

Пагинация

Каналы разбиты на страницы в соответствии с настройкой «книг на странице» экземпляра (по умолчанию 60); размер страницы не управляется клиентом. Каждый список возвращает pagination.nextOffset, когда есть ещё страницы — передайте его как offset в следующем вызове. Представление discover представляет собой случайную выборку и не пагинируется.

Намеренно исключено из области видимости

• Нет записи. В OPDS-канале её нет, и этот сервер не будет её добавлять.

• Нет скачивания файлов. Инструменты возвращают URL для скачивания, а не сами файлы электронных книг.

• Нет навигации по фасетам (авторы/серии/теги/издатели/языки/форматы в виде отдельных индексных каналов). search_books покрывает эти поиски; маршруты существуют, и инструменты для них можно добавить, если возникнет реальная необходимость.

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

• Сервер предназначен только для чтения по своей конструкции — только GET-запросы, никакого состояния.

• Метаданные книг — это ненадёжные данные от третьих лиц; каждый результат сообщает об этом, управляющие символы удаляются, а обработка XML-сущностей отключена (документы, объявляющие DOCTYPE или сущности, отклоняются полностью).

• Ответы ограничиваются по размеру перед парсингом (8 МБ для каналов, 1 МБ для обложек) и снова перед передачей модели (бюджеты на одну книгу и на один ответ).

• Ссылки href в канале передаются только в том случае, если они ведут на настроенный источник по http(s) — враждебный канал не сможет внедрить javascript:, file: или межсайтовые URL в результаты.

• Перенаправления отклоняются, чтобы учётные данные Basic не могли быть воспроизведены на другом хосте; обложки передаются только для реальных типов контента изображений.

• Пароль удаляется из окружения процесса при запуске, а URL очищаются от учётных данных перед появлением в любом логе или результате.

Контейнер

docker run -i --rm \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  ghcr.io/ni-c/calibreweb-mcp

Разработка

npm install
npm test            # unit tests against a stubbed OPDS feed, no instance needed
npm run lint
npm run build

См. CONTRIBUTING.md.

Релиз

1. Обновите CHANGELOG.md и увеличьте версию в package.json (+ lockfile).

2. npm run lint && npm run test:coverage && npm run build

3. Создайте тег релиза: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

Лицензия

MIT