calibreweb-mcp

Ein schreibgeschützter Model Context Protocol-Server für Calibre-Web (und Calibre-Web Automated), die selbst gehostete E-Book-Bibliotheks-Weboberfläche.

Calibre-Web hat keine REST-API – die einzige stabile maschinenlesbare Schnittstelle ist der OPDS-Katalog-Feed, den es für E-Reader-Apps bereitstellt. Dieser Server spricht diesen Feed: Atom XML mit HTTP-Basic-Auth als Eingabe, strukturierte Buchdaten als Ausgabe. Durchsuchen Sie die Bibliothek, blättern Sie durch die kuratierten Ansichten und Regale, folgen Sie formatbezogenen Download-Links und holen Sie Coverbilder direkt in die Konversation. Er schreibt nie etwas: Jedes Tool ist ein GET gegen die OPDS-Routen.

📖 Vollständige Dokumentation: calibreweb-mcp.ni-c.de

Anforderungen

• Node.js 22 oder neuer

• Eine Calibre-Web-Instanz (entwickelt gegen das aktuelle linuxserver/calibre-web-Image; Calibre-Web Automated funktioniert genauso)

• Ein Calibre-Web-Benutzer für den Server. Der OPDS-Feed authentifiziert sich mit dem normalen Web-Login – verwenden Sie ein dediziertes Konto mit nur den Rollen Anzeigen und Herunterladen, nicht Ihr Admin-Konto. Wenn die Instanz anonymes Browsen erlaubt, kann der Server auch ohne Anmeldedaten ausgeführt werden.

Related MCP server: access-calibre

Konfiguration

¹ Lassen Sie beide ungesetzt für eine Instanz, die anonymes Browsen erlaubt; nur eines von beiden zu setzen, ist ein Konfigurationsfehler.

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 = "..." }

Tools

Alle Tools sind schreibgeschützt (readOnlyHint: true).

Bucheinträge enthalten Autoren, Tags, Serien (mit Index), Bewertung, eine gekürzte Zusammenfassung, eine Cover-URL und formatbezogene Download-URLs – fertige Links, die ein Mensch öffnen kann, da das Modell selbst keinen Grund hat, ein EPUB herunterzuladen.

Paginierung

Feeds werden durch die Einstellung Bücher pro Seite der Instanz paginiert (Standard 60); die Seitengröße ist clientseitig nicht steuerbar. Jede Auflistung gibt pagination.nextOffset zurück, wenn weitere Seiten existieren – übergeben Sie es als offset im nächsten Aufruf. Die Ansicht discover ist eine zufällige Auswahl und nicht paginiert.

Bewusst ausgeschlossen

• Keine Schreibvorgänge. Der OPDS-Feed hat keine, und dieser Server würde keine hinzufügen.

• Keine Datei-Downloads. Tools geben Download-URLs zurück, keine E-Book-Nutzdaten.

• Kein Facetten-Browsen (Autoren/Serien/Tags/Verlage/Sprachen/Formate als eigene Index-Feeds). search_books deckt diese Suchvorgänge ab; die Routen existieren und Tools dafür können hinzugefügt werden, wenn es einen echten Anwendungsfall gibt.

Sicherheit

• Der Server ist von Grund auf schreibgeschützt – nur GET-Anfragen, kein Zustand irgendwo.

• Buchmetadaten sind nicht vertrauenswürdige Daten von Drittanbietern; jedes Ergebnis weist darauf hin, Steuerzeichen werden entfernt und die XML-Entity-Verarbeitung ist deaktiviert (Dokumente, die einen DOCTYPE oder Entities deklarieren, werden rundweg abgelehnt).

• Antworten werden vor dem Parsen begrenzt (8 MB Feeds, 1 MB Cover) und erneut, bevor sie das Modell erreichen (Pro-Buch- und Pro-Antwort-Budgets).

• Feed-Hrefs werden nur durchgereicht, wenn sie zum konfigurierten Ursprung über http(s) aufgelöst werden – ein feindlicher Feed kann keine javascript:, file: oder Cross-Origin-URLs in die Ergebnisse einbringen.

• Weiterleitungen werden abgelehnt, sodass die Basic-Anmeldedaten niemals an einen anderen Host weitergereicht werden können; Cover werden nur für echte Bild-Content-Typen durchgereicht.

• Das Passwort wird beim Start aus der Prozessumgebung entfernt, und URLs werden um Anmeldedaten bereinigt, bevor sie in einem Log oder Ergebnis erscheinen.

Container

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

Entwicklung

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

Siehe CONTRIBUTING.md.

Veröffentlichung

1. Aktualisieren Sie CHANGELOG.md und erhöhen Sie die Version in package.json (+ Lockfile).

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

3. Taggen Sie das Release: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

Lizenz

MIT