Calibre MCP

Ein schreibgeschützter Model Context Protocol-Server für eine bestehende Calibre-E-Book-Bibliothek.

Calibre MCP ermöglicht MCP-kompatiblen Clients, Buchmetadaten zu durchsuchen, den Volltextindex von Calibre abzufragen, Buchdetails einzusehen, Bibliothekskategorien zu durchstöbern und verwandte Bücher zu entdecken. Es verwendet die von Calibre unterstützte Befehlszeilenschnittstelle calibredb, anstatt metadata.db direkt zu lesen.

Features

• Metadatensuche mit der Suchsprache von Calibre

• Volltextsuche mit passenden Textausschnitten

• Detaillierte Metadaten für einzelne Bücher

• Zuletzt hinzugefügte Bücher

• Autoren, Schlagwörter, Serien, Verlage und Sprachkategorien

• Entdeckung verwandter Bücher

• MCP-Ressourcen für Bücher, Suchen und Bibliotheksstatus

• Optionale Links zum Calibre Content Server

• In-Memory-TTL-Cache

• Streamable-HTTP-Transport

• Podman-Quadlet-Bereitstellung

• Keine MCP-Tools, die Metadaten verändern

Related MCP server: calibre-manager

Verfügbare Tools

MCP-Ressourcen

Voraussetzungen

• Eine Calibre-Bibliothek mit metadata.db

• Calibre 9.x

• Python 3.11 oder neuer

• Ein MCP-Client, der Streamable HTTP unterstützt

• Podman und systemd für die enthaltene Quadlet-Bereitstellung

Die Volltext-Tools setzen voraus, dass der Volltextindex von Calibre aktiviert und vollständig aufgebaut ist.

Schnellstart mit Podman Quadlet

1. Repository klonen

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

2. Ihre Calibre-Bibliothek bestätigen

Das mitgelieferte Quadlet geht von Folgendem aus:

/tank/media/Books

Bestätigen Sie, dass die Bibliotheksdatenbank vorhanden ist:

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

3. Den Besitzer der Bibliothek ermitteln

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

Bearbeiten Sie quadlet/calibre-mcp.container und setzen Sie User= auf die zurückgegebene numerische UID und GID:

User=1000:1000

Ändern Sie außerdem den Host-Bibliothekspfad, falls Ihrer abweicht:

Volume=/tank/media/Books:/books

4. Image erstellen

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

5. Quadlet installieren

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

Führen Sie systemctl enable calibre-mcp.service nicht aus. Der erzeugte Dienst ist transient; der Abschnitt [Install] des Quadlets erstellt die Boot-Abhängigkeit.

6. Bereitstellung überprüfen

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

Überprüfen Sie Calibre im 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

Der Standard-Endpunkt ist:

http://localhost:8008/mcp

Mit MCP Inspector testen

npx @modelcontextprotocol/inspector

Wählen Sie Streamable HTTP und verbinden Sie sich mit:

http://YOUR_SERVER:8008/mcp

Beispiel für eine Metadatensuche:

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

Beispiel für eine Volltextsuche:

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

Beispiel für eine eingeschränkte Volltextsuche:

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

Einen MCP-Client verbinden

Verwenden Sie den vom Server bereitgestellten Streamable-HTTP-Endpunkt:

http://YOUR_SERVER:8008/mcp

Die Konfigurationsformate der Clients variieren. Konsultieren Sie die MCP-Dokumentation Ihres Clients und wählen Sie Streamable HTTP statt stdio oder Legacy-SSE.

Beispiele für Calibre-Suchen

search_books akzeptiert Calibre-Suchausdrücke:

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

Eine leere Abfrage gibt alle Bücher zurück, vorbehaltlich des Ergebnislimits.

Optionale Content-Server-Links

Setzen Sie die URL Ihres vorhandenen Calibre Content Servers im Quadlet:

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

Wenn konfiguriert, enthalten die Metadaten-Ergebnisse Links zum Anzeigen im Browser und zum Herunterladen von Formaten.

Konfiguration

Warum der Bibliotheks-Mount beschreibbar ist

Calibre prüft, ob das Dateisystem der Bibliothek case-sensitiv ist, indem es kurzzeitig eine Testdatei im Stammverzeichnis der Bibliothek erstellt und wieder löscht. Folglich kann der Bind-Mount nicht schreibgeschützt eingehängt werden.

Dieser Server bleibt funktional schreibgeschützt, da er keine Tools bereitstellt, die Calibre-Befehle wie die folgenden aufrufen:

• add

• remove

• set_metadata

• add_format

• remove_format

Führen Sie den Container mit derselben unprivilegierten UID und GID aus, der die Bibliothek gehört. Führen Sie ihn nicht als root aus, es sei denn, Ihre Umgebung erfordert dies ausdrücklich.

Sicherheit

• Halten Sie Port 8008 auf vertrauenswürdige LAN- oder Tailscale-Clients beschränkt.

• Setzen Sie den Endpunkt nicht direkt dem öffentlichen Internet aus.

• Streamable HTTP fügt in dieser Bereitstellung keine Authentifizierung hinzu.

• Platzieren Sie vor einer breiteren Freigabe einen authentifizierenden Reverse-Proxy vor dem Dienst.

• Pinnen Sie Release-Versionen, anstatt ein sich änderndes Container-Tag zu verwenden.

• Lesen Sie SECURITY.md, bevor Sie eine Sicherheitslücke melden.

Red-Team-Härtung (Runde 1)

Zehn adversariale Angriffsvektoren wurden mit fehlschlagenden Tests nachgewiesen und anschließend behoben. Jeder TestAttack_*-Test in tests/attack_round1_test.py ist eine dauerhafte Regressions-Fixture für seinen Vektor.

In dieser Runde verifizierte, bekanntermaßen sichere Oberflächen: Shell-Injektion (argv-Liste, kein shell=True), Optionswert-Injektion (--sort-by/--categories/--restrict-to lehnen Werte mit führendem Bindestrich im Parser von Calibre ab), Pfad-Traversal bei Ressourcen-URIs (nicht-numerische IDs abgelehnt), Ergebnislimit-Begrenzung (_limit) und Cache-Race-Conditions (durch Sperren geschützt).

Red-Team-Härtung (Runde 2)

Sechs Validierungsvektoren für die Eingabeform wurden nachgewiesen und behoben; Fixtures in tests/attack_round2_test.py.

Red-Team-Härtung (Runde 3)

Drei Fehlerpfad-Robustheitsvektoren wurden nachgewiesen und behoben; Fixtures in tests/attack_round3_test.py.

Red-Team-Härtung (Runde 4)

Zwei Nebenläufigkeits-/Prozessflut-Vektoren wurden nachgewiesen und behoben; Fixtures in tests/attack_round4_test.py.

Red-Team-Härtung (Runde 5 — abschließende Verifikation)

Keine neuen Schwachstellen. Ein Audit der Abdeckungslücken fügte 11 Verifikationstests (tests/attack_round5_test.py) hinzu, die jeden noch nicht von den Runden 1–4 abgedeckten Einstiegspunkt testen — search_resource, book_resource (nicht-numerisch, traversal-artig, im gültigen Bereich), status_resource, library_status, list_recent_books, clear_cache, search_fulltext-Listen-Payloads, Null-/Negativ-Limits, Cache-Deaktivierung bei TTL null und Leerzeichen-Abfragen. Alle bestanden sofort und bestätigen, dass die Abwehrmaßnahmen der Runden 1–4 auf der gesamten Tool-/Ressourcenoberfläche Bestand haben.

Zwei Dokumentationsbefunde zur Bereitstellungshaltung wurden in SECURITY.md festgehalten (keine Codeänderung): die Containerfile hat keine USER-Direktive (läuft als root, wenn sie außerhalb des Quadlet erstellt wird, das User=1000:1000 setzt), und das Quadlet setzt SecurityLabelDisable=true (SELinux-Label-Trennung ist deaktiviert).

Lokale Entwicklung

Virtuelle Umgebung erstellen:

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

Tests ausführen:

pytest

Lint-Prüfungen ausführen:

ruff check .

Server lokal starten:

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

Projektstatus

Version 1.0.0 eignet sich für persönliche Bereitstellungen und Bereitstellungen in vertrauenswürdigen Netzwerken. Die öffentliche API kann in zukünftigen Minor-Releases zusätzliche Tools und Ressourcen erhalten, während bestehende Tool-Namen und Argumentformen nach Möglichkeit stabil gehalten werden.

Mitwirken

Issues und Pull-Requests sind willkommen. Siehe CONTRIBUTING.md.

Lizenz

Veröffentlicht unter der MIT-Lizenz.