CalibreMCP
📖 Installation Guide — download the
.exefrom 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.
Claude Desktop one-liner (MCPB bundle): download calibre-mcp.mcpb from Releases and install via Settings → MCP Servers → Install from file.
Developers from source:
git clone https://github.com/sandraschi/calibremcp
cd calibremcp
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 33 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:
-
Calibre Content Server (
http://goliath:8099/orhttp://localhost:8080/):- How it is served: Built directly into the core Calibre engine (
calibre.exe --start-in-trayor headlesscalibre-server.exe). It executes an asynchronous Python HTTP/1.1 daemon (calibre.srv) delivering a compiled Single Page Application bundled insideresources/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.jswith 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.
- How it is served: Built directly into the core Calibre engine (
-
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.
- Remote access: loopback-only by default (
start.ps1); runwebapp/start-lan.ps1for LAN / Tailscale access from phone, tablet, or a second PC (no auth — trusted networks only). See Remote Access.
- How it is served: Modern Next.js 15 App Router (React 19, TypeScript, Tailwind CSS) backed by a FastAPI async server (
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
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/calibremcp.git
cd calibremcp
uv sync
# Or via MCPB package
npx mcpb install calibre-mcp
Features
- FastMCP 3.2 — Universal connect (stdio + HTTP), sampling, agentic tool chaining
- 33 portmanteau tools — Consolidated operations (search, manage, export, OCR, viewer, canon, contents)
- Canon Coverage — Gap analysis vs Gutenberg Top 100, Nobel laureates, Delphi catalog, pasted lists
- Collection contents — Delphi-style omnibus TOC index; contained works searchable, never counted
- 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, tag management, bulk ops, and LAN/Tailscale remote access via
start-lan.ps1 - 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.
