Skip to main content
Glama

Calibre MCP Server

by Miguel0888
OverviewSchemaRelated ServersScoreDiscussions
Python
Local
# Calibre MCP Server Ein experimenteller [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) Server, der auf eine lokale [Calibre](https://calibre-ebook.com/) Bibliothek zugreift. Ziel ist es, KI-Agenten (z. B. ChatGPT, Copilot, Claude Desktop) ein Research-API auf deine E-Book-Sammlung zu geben – inklusive Fulltext-Suche und strukturierten Excerpts. Zusätzlich gibt es ein Calibre-GUI-Plugin, das den MCP-Server direkt aus Calibre heraus startet und stoppt. --- ## Features (aktueller Stand) - MCP-Server auf Basis von `fastmcp` - Tool `calibre_fulltext_search` - Tool `calibre_get_excerpt` - Zugriff auf Calibre-`metadata.db` via SQLite (read-only) - Volltext-ähnliche Suche über Titel, ISBN und Kommentare (`books` + `comments`) - Auflösen von Büchern über ISBN (inkl. `identifiers`-Tabelle) - Domänenschicht `LibraryResearchService` als zentrale API - Calibre-GUI-Plugin, das den MCP-Server als Subprozess startet/stoppt - Zwei kleine Testskripte zum manuellen Testen gegen eine echte Bibliothek --- ## Repository-Struktur Wichtige Verzeichnisse/Dateien: - `pyproject.toml` – Projekt- und Dependency-Definitionen - `src/calibre_mcp_server/` – MCP-Server und Domänencode - `core/models.py` – einfache Domain-Modelle (`FulltextHit`, `Excerpt` …) - `core/service.py` – `LibraryResearchService`, zentrale Research-API - `infra/metadata_sqlite.py` – Zugriff auf `metadata.db` über SQLite - `tools/ft_search_tool.py` – MCP-Tool `calibre_fulltext_search` - `tools/excerpt_tool.py` – MCP-Tool `calibre_get_excerpt` - `main.py` – Einstiegspunkt für den MCP-Server (`python -m calibre_mcp_server.main`) - `calibre_plugin/` – Calibre-GUI-Plugin - `__init__.py` – Plugin-Metadaten für Calibre - `action.py` – GUI-Action, startet/stoppt den MCP-Server - `tests/` – manuelle Testskripte - `manual_test_service.py` – einfacher End-to-End-Test für den Service - `inspect_metadata_isbn.py` – Debug-Script, das zeigt, wie eine ISBN in `metadata.db` gespeichert ist --- ## Voraussetzungen - Python 3.10+ (getestet mit 3.12) - Eine lokale Calibre-Bibliothek - z. B. `X:\E-Books` mit `metadata.db` im Root - Entwicklungsabhängigkeiten (werden über `pip` installiert): - `fastmcp` - `pydantic` - plus alles, was in `pyproject.toml` steht --- ## Installation (Development Setup) ```bash # Repository klonen git clone https://github.com/Miguel0888/mcp-server.git cd mcp-server # Optional: virtuelles Environment anlegen python -m venv .venv # Windows: .venv\Scripts\activate # Linux/macOS: # source .venv/bin/activate # Paket im Editable-Mode installieren (inkl. Dependencies) python -m pip install -e .

Danach ist das Paket calibre_mcp_server im aktiven Python-Interpreter importierbar.

MCP-Server manuell starten

Voraussetzung: Environment-Variable CALIBRE_LIBRARY_PATH muss auf den Root deiner Calibre-Bibliothek zeigen (dort, wo metadata.db liegt).

Beispiel (Windows):

set CALIBRE_LIBRARY_PATH=X:\E-Books python -m calibre_mcp_server.main

Du solltest die FastMCP-Banner-Ausgabe sehen und der Server wartet dann auf MCP-Client-Verbindungen über STDIO.

In einer MCP-fähigen IDE / einem MCP-Client (z. B. ChatGPT, Claude Desktop, Copilot Agent Mode) kann dieser Command als MCP-Server registriert werden und die Tools calibre_fulltext_search und calibre_get_excerpt verwenden.

Manuelle Tests gegen eine echte Bibliothek

1. tests/manual_test_service.py

Dieses Script testet die Domänenschicht LibraryResearchService direkt – ohne MCP und ohne Calibre-Plugin.

Anpassen in tests/manual_test_service.py:

library_path = r"X:\E-Books" # Pfad zu deiner Calibre-Bibliothek # Eine Query, von der du erwartest, dass sie Treffer liefert query = "der" # Eine echte ISBN aus deiner Bibliothek test_isbn = "9783446429338"

Ausführen:

python tests\manual_test_service.py

Erwartetes Verhalten:

  • fulltext_search gibt eine Liste von Treffern (FulltextHit) mit book_id, title, isbn (falls vorhanden) und einem kurzen Snippet aus Kommentaren/Titel zurück.

  • get_excerpt_by_isbn findet das Buch zu test_isbn über die identifiers-Tabelle und gibt einen einfachen Excerpt zurück (aktuell aus comments oder – wenn leer – dem Titel).

2. tests/inspect_metadata_isbn.py

Dieses Script hilft beim Debuggen von ISBN-Mapping und zeigt, wie Calibre die Daten in metadata.db speichert.

Konfiguration im Script:

library_root = r"X:\E-Books" # Default-ISBN (kann per CLI-Argument überschrieben werden) raw_isbn = "9783446429338"

Ausführen ohne Argument (nutzt die Default-ISBN):

python tests\inspect_metadata_isbn.py

Oder mit einer anderen ISBN:

python tests\inspect_metadata_isbn.py 9781484265611

Das Script zeigt u. a.:

  • Schema von books und identifiers

  • alle Zeilen in books.isbn, die zur normalisierten ISBN passen

  • alle Zeilen in identifiers.val, die passen (inkl. book-ID und Typ)

  • zugehörige Bücher inkl. Kommentaren (falls vorhanden)

Calibre-GUI-Plugin

Im Ordner calibre_plugin/ liegt ein einfaches GUI-Plugin, mit dem du den MCP-Server direkt aus Calibre heraus starten und stoppen kannst.

Aufbau

  • calibre_plugin/__init__.py

    • beschreibt das Plugin für Calibre (Name, Version, min. Calibre-Version, etc.)

    • verweist mit actual_plugin = "action:McpInterfaceAction" auf die Implementierung

  • calibre_plugin/action.py

    • definiert McpInterfaceAction (Unterklasse von InterfaceAction)

    • fügt eine Toolbar-/Menü-Aktion "MCP Server" hinzu

    • beim Klick: Start/Stopp eines Subprozesses mit python -m calibre_mcp_server.main

    • setzt CALIBRE_LIBRARY_PATH automatisch auf die aktuell geöffnete Bibliothek (self.gui.current_db.library_path)

Manuell ein Plugin-ZIP bauen

Im Projekt-Root:

mkdir -p dist cd calibre_plugin zip -r ..\dist\calibre-mcp-plugin.zip .

Die ZIP-Datei dist/calibre-mcp-plugin.zip enthält dann direkt __init__.py und action.py (genau so erwartet Calibre das).

Plugin in Calibre installieren

  1. Calibre öffnen

  2. Einstellungen → Plugins → "Plugin aus Datei laden"

  3. calibre-mcp-plugin.zip auswählen

  4. Calibre neu starten

Danach sollte in der Toolbar oder im Menü ein Eintrag "MCP Server" vorhanden sein.

  • Erster Klick → startet den MCP-Server (externes python), setzt CALIBRE_LIBRARY_PATH

  • Zweiter Klick → beendet den Serverprozess

Wichtig: In der Python-Umgebung, die Calibre für python nutzt, muss das Paket calibre_mcp_server installiert sein, z. B.:

python -m pip install -e .

(ggf. mit dem Python, das in PATH liegt oder explizit in action.py konfiguriert wird.)

GitHub Actions: automatischer Build & Release des Plugins

Lege die Datei .github/workflows/release.yml an mit:

name: Release Calibre MCP Server on: push: tags: - 'v*' jobs: build-and-release: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.12' - name: Install package (editable) run: | python -m pip install --upgrade pip python -m pip install -e . - name: Smoke test (compile sources) run: | python -m compileall src - name: Build Calibre plugin zip run: | mkdir -p dist cd calibre_plugin zip -r ../dist/calibre-mcp-plugin.zip . - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: files: dist/calibre-mcp-plugin.zip env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Was der Workflow tut:

  1. Läuft bei push auf Tags, die mit v beginnen (z. B. v0.1.0).

  2. Checkt das Repo aus.

  3. Installiert dein Paket im Editable-Mode.

  4. Führt einen kleinen Smoke-Test aus (compileall).

  5. Baut dist/calibre-mcp-plugin.zip aus dem Ordner calibre_plugin.

  6. Erzeugt (falls nötig) einen GitHub Release zum Tag und hängt das ZIP als Asset an.

Release auslösen

Im Repo-Root:

# Version bump + commit (optional) git commit -am "Bump version to v0.1.0" # Tag erstellen git tag v0.1.0 # Tag pushen git push origin v0.1.0

Danach solltest du im GitHub-UI unter „Actions“ den Workflow sehen und unter „Releases“ dann den neuen Release mit angehängter calibre-mcp-plugin.zip.

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Miguel0888/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server