CalibreMCP

📖 Installation Guide — download the .exe from Releases, double-click, done

FastMCP 3.2 MCP server for Calibre e-book library management — AI-assisted search, RAG, and agentic workflows for Sandra's 1000+ book library.

Quick Start

Download Calibre MCP_*_x64-setup.exe from Releases → double-click → launch Calibre MCP. Install guide.

Developers from source:

git clone https://github.com/sandraschi/calibre-mcp
cd calibre-mcp
just sync
just start-webapp

// claude_desktop_config.json { "mcpServers": { "calibre-mcp": { "command": "uv", "args": ["run", "calibre-mcp"], "env": { "CALIBRE_LIBRARY_PATH": "L:/Multimedia Files/Written Word/Calibre-Bibliothek" } } } } Then ask Claude: "Find unread sci-fi books", "Open a random Banks novel", or "What's my library health?"

What is this?

calibre-mcp bridges your Calibre e-book library and AI assistants (Claude Desktop, Cursor, etc.) via the Model Context Protocol. It reads Calibre's metadata.db directly, indexes metadata for semantic search (LanceDB RAG), and exposes 21 portmanteau tools for natural-language library management.

Full Architecture & Technology Stack

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                   CLIENT INTERFACES                                    │
│  ┌───────────────────────┐  ┌─────────────────────────┐  ┌──────────────────────────┐  │
│  │     Claude Desktop    │  │   Calibre MCP WebApp    │  │  Calibre GUI + Plugin    │  │
│  │   (MCP stdio / MCPB)  │  │  (Next.js 15 @ :10721)   │  │   (Qt6 / PyQt5 Plugin)   │  │
│  └───────────┬───────────┘  └────────────┬────────────┘  └────────────┬─────────────┘  │
└──────────────┼───────────────────────────┼────────────────────────────┼────────────────┘
               │ JSON-RPC (stdio)          │ REST / SSE                 │ Direct SQLite
               ▼                           ▼                            ▼
┌───────────────────────────────────────────────────────┐  ┌─────────────────────────────┐
│             CALIBRE-MCP BACKEND (:10720)              │  │    CALIBRE CONTENT SERVER   │
│                                                       │  │       (e.g. :8099)          │
│  ┌─────────────────────────────────────────────────┐  │  │                             │
│  │ FastMCP 3.2 Server + Tool Registry (21 tools)   │  │  │  - Async Python Engine      │
│  │ - Reciprocal Rank Fusion (RRF) Hybrid Search    │  │  │    (calibre.srv)            │
│  │ - Incremental LanceDB RAG Sync                  │  │  │  - RapydScript SPA          │
│  │ - Portmanteau CRUD & Library Health Engine      │  │  │    (index-generated.html)   │
│  └─────────────────────────────────────────────────┘  │  │  - HTML5 In-Browser Reader  │
│  ┌─────────────────────────────────────────────────┐  │  │    (viewer.js / offline SW) │
│  │ FastAPI REST Layer + Async Background Workers   │  │  │  - OPDS Mobile Catalog Feed │
│  └─────────────────────────────────────────────────┘  │  └──────────────┬──────────────┘
└──────────────┬───────────────────────────┬────────────┘                 │
               │                           │                              │
               ▼                           ▼                              ▼
┌──────────────────────────────┐  ┌──────────────────────────────────────────────────────┐
│       AI / VECTOR LAYER      │  │                   DATA STORAGE LAYER                 │
│  - LanceDB (Metadata & FTS)  │  │  - metadata.db (Calibre SQLite catalog)              │
│  - fastembed (BAAI/bge-small)│  │  - full-text-search.db (Calibre FTS5 token index)    │
│  - Ollama / OpenAI Provider  │  │  - calibre_mcp_data.db (Sidecar extended metadata)   │
└──────────────────────────────┘  └──────────────────────────────────────────────────────┘

Dual WebApp Ecosystem: Calibre Content Server vs CalibreMCP

In a production Calibre environment, two distinct web applications operate side-by-side:

1. Calibre Content Server (http://goliath:8099/ or http://localhost:8080/):

   • How it is served: Built directly into the core Calibre engine (calibre.exe --start-in-tray or headless calibre-server.exe). It executes an asynchronous Python HTTP/1.1 daemon (calibre.srv) delivering a compiled Single Page Application bundled inside resources/content-server/index-generated.html (~3.9 MB, transpiled from Python-like AST to ES6 JavaScript using RapydScript).
   • Why it looks similar to our webapp: Both webapps share identical data models and UX design patterns: a responsive card grid of book covers with hover elevation, left-hand faceted sidebar filtering (Authors, Series, Tags, Formats, Publishers, Virtual Libraries), instant search bar, and dark-themed detail drawers.
   • Core strengths: State-of-the-art in-browser e-book reading (viewer.html/viewer.js with offline reading via ServiceWorkers, highlights, annotations, bookmarks, and font settings), native OPDS feeds for mobile readers (KyBook, Moon+ Reader), and direct format conversion.
   • Remote access: Easily exposed across local subnets, fixed IPs, or zero-config WireGuard overlays like Tailscale.

2. CalibreMCP WebApp (http://localhost:10721/, backend :10720):

   • How it is served: Modern Next.js 15 App Router (React 19, TypeScript, Tailwind CSS) backed by a FastAPI async server (app.main:app) running FastMCP 3.2.
   • Core strengths: AI-native intelligence: conversational AI librarian (Ollama, LM Studio, OpenAI), hybrid semantic search (Reciprocal Rank Fusion combining FTS5 lexical ranking with LanceDB vector embeddings), automated library health scans, duplicate book candidate clustering, smart dynamic virtual shelves, and direct embedded reading overlays.

Together, Calibre Content Server provides the high-performance reading and distribution engine, while CalibreMCP provides the conversational AI, semantic discovery, and automated library maintenance engine.

Read more

Topic	Description
About Calibre	What Calibre is, how it stores data, access methods
About Calibre Web	Calibre Content Server (modern SPA) vs calibre-web vs CalibreMCP
About Plugins	CalibreMCP Integration plugin, calibreops-bridge, roadmap
About MCP Tools	21 portmanteau tools, architecture, agentic flows
About AI Workflows	RAG, FTS, skills, prompts, sampling, agentic chaining

Key links

• Documentation hub — curated entry
• Documentation index — full map of ~100 docs
• Tauri desktop — maintainer build and production pitfalls
• Cookbook — goal-oriented recipes
• API reference — all MCP tools and endpoints
• Configuration — env vars and library setup
• Troubleshooting — common issues and fixes
• Webapp README — Next.js dashboard on ports 10720/10721
• Plugin README — Calibre GUI plugin install and usage
• Plugin repo — calibreops-bridge (RAG/AI plugin)

Installation

# Development install
git clone https://github.com/sandraschi/calibre-mcp.git
cd calibre-mcp
uv sync

# Or via MCPB package
npx mcpb install calibre-mcp

Features

• FastMCP 3.2 — Universal connect (stdio + HTTP), sampling, agentic tool chaining
• 21 portmanteau tools — Consolidated operations (search, manage, export, OCR, viewer)
• Metadata RAG (LanceDB) — Semantic search over title, authors, tags, comments
• Full-text chunk RAG — FTS-driven book content retrieval
• Calibre FTS — Phrase search with PDF page / EPUB spine locations
• Calibre plugin — Extended metadata editor + VL from query in Calibre GUI
• Webapp — Next.js dashboard with AI chat, Semantic Search, Skills, Smart Import
• Skills & prompts — Reusable agentic workflows (recommendations, library health, etc.)
• Concurrency-safe — Thread-safe DB operations for multi-client access
• Windows-native — Unicode-safe, runs reliably on Windows

Austrian efficiency for digital libraries. Built with realistic AI-assisted development timelines.