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.
Mutations stay hidden unless Calibre is exactly version 9.12.0, the plugin UI contains a saved bearer token, mutation discovery is enabled and any environment-token override matches. 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.