calibre-mcp

Ein lokaler MCP-Server (stdio), der es einem LLM-Host – Claude Desktop, Claude Code oder einem beliebigen MCP-kompatiblen Client – ermöglicht, eine Calibre-E-Book-Bibliothek im Gespräch zu verwalten: suchen, Metadaten bearbeiten, hinzufügen, konvertieren, deduplizieren, entfernen und Bücher per E-Mail versenden – alles mit Sicherheit durch menschliche Bestätigung (Human-in-the-Loop).

Die meisten Calibre-MCP-Server sind schreibgeschützt – sie suchen und listen. Dieser hier schreibt – und das sicher. Metadaten bearbeiten, hinzufügen, konvertieren und Bücher löschen sind genau die Stellen, an denen ein Tool deine Bibliothek tatsächlich beschädigen oder verlieren kann. Deshalb läuft hier jede Änderung über ein Design, das genau das unmöglich macht – auch versehentlich:

• Plan → Bestätigung bei jeder destruktiven Aktion. Der erste Aufruf liefert eine menschenlesbare Diff-Ansicht und ein confirmation_token; nichts wird geändert, bis du mit genau diesem Token erneut aufrufst.

• Automatisches metadata.db-Backup vor jedem Schreibvorgang (rollierend, die letzten 20).

• Wiederherstellbare Löschungen – Sicherungskopie und Calibre-Papierkorb, niemals ein endgültiges Löschen.

• Lesen kann nichts beschädigen – die SQLite-Verbindung wird mit mode=ro geöffnet.

Entwickelt, um das Klicken durch die Calibre-GUI zu beenden und eine Bibliothek stattdessen aus einem Chat zu verwalten – und bewusst als Beispiel dafür gestaltet, wie man ein Tool entwirft, das Dateien des Benutzers löschen darf: hybrides I/O-Design, eine explizite Fehler-Taxonomie, menschliche Genehmigungsschwellen bei jeder destruktiven Aktion und eine Testsuite, die niemals echte Benutzerdaten anfasst. Siehe PRODUCT.md für das Was und Warum und ARCHITECTURE.md für die vollständige Design-Beschreibung.

Warum das hybride Design

• Lesen (search, list, view, Duplikatsuche) fragt metadata.db direkt ab, nur lesend – schnell und strukturell nicht in der Lage, die Bibliothek zu beschädigen (die SQLite-Verbindung wird mit mode=ro geöffnet).

• Schreiben (edit, add, remove, convert, email) läuft über Calibres eigene CLI-Werkzeuge (calibredb, ebook-convert, calibre-smtp) – niemals über rohes SQL –, damit Calibre die Autorität über seine eigene Datenbank behält.

• Vor jedem Schreibvorgang wird ein automatisches metadata.db-Backup erstellt (rollierend, behält die letzten 20).

• Entfernen ist wiederherstellbar: Dateien werden in einen verwalteten Papierkorb-Ordner kopiert und das Buch wird in den Calibre-Papierkorb verschoben – niemals ein endgültiges Löschen.

• Jedes verändernde oder nach außen gerichtete Tool ist zweistufig (Plan → Bestätigung): Der erste Aufruf liefert eine menschenlesbare Übersicht plus ein confirmation_token; nichts wird geändert – und nichts gesendet –, bis du mit genau diesem Token erneut aufrufst.

Die vollständige Begründung, Modulgrenzen und das Entscheidungsprotokoll hinter diesen Entscheidungen findest du in ARCHITECTURE.md.

Related MCP server: calibre-mcp

Voraussetzungen

• Calibre installiert, mit calibredb und ebook-convert in deinem PATH (calibredb --version). calibre-smtp wird ebenfalls benötigt, wenn du email_book verwenden möchtest.

• Python ≥ 3.12 und uv.

Installation

Ohne Klonen (empfohlen) – uv baut und führt es direkt aus dem Repository aus, ohne manuelles Checkout:

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

Aus einem lokalen Checkout (für Entwicklung oder um einen bestimmten Stand festzunageln):

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

Konfiguration

Der Server verwaltet eine Bibliothek, die über eine Umgebungsvariable festgelegt wird:

Der Server bricht beim Start sofort ab mit einer klaren Fehlermeldung, wenn CALIBRE_LIBRARY_PATH nicht gesetzt ist oder das Verzeichnis keine metadata.db enthält.

email_book benötigt zusätzlich SMTP-Relay-Zugangsdaten (lazy geladen – der Server startet auch ohne sie problemlos, und nur email_book schlägt fehl, wenn sie fehlen):

Claude Desktop / Claude Code

Füge es zu deiner MCP-Konfiguration hinzu (z. B. claude_desktop_config.json). Ohne Klonen – läuft direkt aus dem Repository über 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"
      }
    }
  }
}

Oder aus einem lokalen Checkout:

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

Manuell ausführen

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

Der Server kommuniziert über stdio (JSON-RPC); er gibt nichts auf stdout aus außer MCP-Framing – alle Logs gehen absichtlich auf stderr (siehe ARCHITECTURE.md).

Werkzeuge

Zusätzlich gibt es eine MCP-Ressource, calibre://library/stats – ein aggregiertes Bibliotheksprofil (Gesamtzahlen, Format-/Sprachmischung, Metadaten-Vollständigkeit, Datenqualitäts-Flags), das ohne jeden Tool-Aufruf lesbar ist.

Der vollständige Vertrag jedes Werkzeugs (Randfälle, Fehlerbedingungen, exakte Feld-Whitelist) ist in seinem Docstring in server.py dokumentiert – diese Docstrings sind das, was der LLM-Host sieht, und dienen daher gleichzeitig als API-Referenz.

Entwicklung

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 Tests in drei Stufen (unit, integration, e2e); Schreibtests berühren niemals eine echte Bibliothek – siehe ARCHITECTURE.md.

Projektstruktur

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

Roadmap

Bereits geliefert: vollständige Lese-/Kuratier-/Verteil-Schleife (suchen, listen, ansehen, bearbeiten, hinzufügen, entfernen, konvertieren, deduplizieren, per E-Mail senden). Was als Nächstes kommt – Bibliotheks-Selbstwissen, Stapeloperationen, Cover-/Metadaten-Anreicherung, Gerätesynchronisierung – ist in .specs/ROADMAP.md festgehalten, einschließlich der Begründung für die Reihenfolge und was explizit außerhalb des Rahmens liegt.

Mitwirken

Siehe CONTRIBUTING.md für den Entwicklungs-Workflow, die Invarianten, die ein PR bewahren muss, und wie der spezifikationsgetriebene Prozess hinter diesem Repository funktioniert.

Lizenz

MIT © Gustavo F Sousa.