python-umcp-calibre runs an MCP server inside the Calibre GUI process. Agents can search libraries, inspect books and, when explicitly enabled, perform mutations through Calibre's own APIs and job system.
The process boundary matters because Calibre keeps database, cache and filesystem state in memory. The plugin never opens metadata.db independently and does not switch the visible library as a side effect of a read.
The released plugin serves Streamable HTTP at POST /mcp. Read-only tools expose library aliases, searches, metadata, formats, bounded EPUB inspection, quality assessment, duplicate discovery and bridge job state. Inactive libraries use Calibre secondary handles.
Writes must be explicitly enabled and are restricted to the supported Calibre version, currently 9.12.0, with a bearer token saved in the plugin UI. Additional configuration checks prevent accidental enablement. Short operations run on the GUI thread; conversion, import and other long tasks use Calibre's native job machinery.
Reads and writes execute inside the GUI process, preserving Calibre's in-memory database and cache invariants.
Clients begin with a compact capability surface and can request one tool schema at a time. Results use stable ordering, opaque cursors and truncation metadata.
Checks container structure, metadata, cover, table of contents and content signals under explicit file, archive, expansion, scan and time limits. Book text and absolute paths are not returned.
Scores EPUB quality with reason codes, compares candidates and finds duplicates within or across configured libraries without changing the active GUI library.
Supports metadata, formats, covers, import, trash, duplicate merge, conversion, library copy or move, disk export, configured e-mail recipients, job cancellation and guarded library switching.
Import and export roots, destination libraries and recipients are configured in the UI. Non-loopback MCP access requires a bearer token; an environment token alone cannot unlock writes.
Long operations appear in Calibre's Jobs UI and in the bridge ledger. Cancellation and cross-library moves report partial work instead of promising atomic behaviour.
The repository retains an older read-only stdio/HTTP server and JSON-RPC helper, but neither is the released mutation surface.