calibre-mcp

Un servidor MCP que da a los asistentes de IA (Claude Code, Claude Desktop, Cursor, ...) acceso de lectura y escritura a tu biblioteca local de libros electrónicos de Calibre.

Busca en la biblioteca, explora las incorporaciones recientes, importa nuevos libros electrónicos con detección automática de duplicados y gestiona una bandeja de entrada de «carpeta de descarga» — todo desde el chat.

• Configuración cero en una instalación normal: el ejecutable calibredb y la biblioteca que usa tu interfaz gráfica de Calibre se detectan automáticamente en macOS, Windows y Linux.

• Independiente de la configuración regional: todas las lecturas pasan por calibredb --for-machine (JSON), por lo que los resultados nunca dependen del idioma de la interfaz de Calibre.

• Seguro por defecto: la detección de duplicados se basa en el propio Calibre — un libro cuyo título + autor ya esté en la biblioteca se omite, nunca se importa dos veces.

Herramientas

Related MCP server: Calibre MCP Server

Requisitos

• Calibre (cualquier versión que incluya calibredb; probado con 9.x)

• Python ≥ 3.10

Instalación

pipx (recomendado)

pipx install calibre-mcp

uv

uv tool install calibre-mcp

pip

pip install calibre-mcp

Desde el código fuente

git clone https://github.com/ZehuiTIAN/calibre-mcp.git
cd calibre-mcp
pip install -e ".[dev]"     # dev extras add pytest + ruff

Configuración

Todo es opcional en una instalación normal; cada valor se puede fijar con una variable de entorno.

Registro con Claude Code

claude mcp add calibre-mcp -- calibre-mcp

o añade a ~/.claude.json → mcpServers (ámbito de usuario):

"calibre_mcp": {
  "type": "stdio",
  "command": "calibre-mcp",
  "args": [],
  "env": {
    "CALIBRE_LIBRARY_PATH": "/path/to/your/library",
    "CALIBRE_INBOX_DIR": "/path/to/your/inbox"
  }
}

Registro con Claude Desktop / Cursor

Añade el mismo bloque JSON a la sección de servidores MCP de claude_desktop_config.json (Claude Desktop) o a la configuración de MCP de Cursor.

Flujo de trabajo de la bandeja de entrada

Una carpeta de descarga crea un bucle agradable de «buscar → soltar → archivar» para los libros que descargas a mano:

1. Apunta CALIBRE_INBOX_DIR a una carpeta, p. ej. ~/Downloads/Calibre-Inbox.

2. Descarga libros electrónicos en esa carpeta.

3. Pide a tu asistente que ejecute import_inbox.

Cada archivo se añade a la biblioteca; los archivos añadidos correctamente y los duplicados se archivan en imported/YYYY-MM/, y los fallos en failed/ — la bandeja de entrada en sí se mantiene limpia, y nunca se sobrescribe nada (los conflictos de nombre reciben un sufijo -1, -2, ...).

Extensiones admitidas: .epub .pdf .mobi .azw .azw3 .djvu .cbz .cbr .fb2 .txt .md .docx .rtf .lit .prc .pdb .chm .htmlz.

Advertencias

• Bloqueo de la base de datos: mientras la interfaz gráfica de Calibre tenga la biblioteca abierta, las operaciones de escritura (add_books, import_inbox) pueden fallar con un error de bloqueo de la base de datos. Las herramientas de solo lectura siguen funcionando. Cierra Calibre (o cámbialo a otra biblioteca) antes de importar.

• Bibliotecas grandes: add_books/import_inbox toman una instantánea del conjunto completo de ids de libros alrededor de cada adición, lo que en la práctica es rápido, pero es O(número de libros) por importación.

• Esta herramienta solo organiza tu biblioteca. No contiene ninguna función de búsqueda ni descarga; úsala con contenido que tengas derecho a conservar.

Desarrollo

pip install -e ".[dev]"
ruff check .
pytest -m "not integration"      # unit tests, run anywhere
pytest                           # + integration tests (need local calibre)

Las pruebas de integración crean bibliotecas desechables en /tmp y nunca tocan tu biblioteca real.

Licencia

MIT — ver LICENSE.

Resumen rápido en chino

Un servidor MCP que conecta tu biblioteca local de Calibre a asistentes de IA como Claude/Cursor: cinco herramientas (library_info / search_books / list_books / add_books / import_inbox), detección automática de calibredb y de la ubicación de la biblioteca, listo para usar en todas las plataformas (Windows/macOS/Linux).

pipx install calibre-mcp
claude mcp add calibre-mcp -- calibre-mcp

Al importar, se detectan automáticamente los duplicados (los libros con el mismo título + autor no se importan dos veces); con el directorio de bandeja de entrada CALIBRE_INBOX_DIR, basta con dejar los libros descargados y decir «importar bandeja de entrada» para archivarlos; los archivos procesados se clasifican automáticamente en imported/ o failed/.

Nota: si el programa de escritorio de Calibre tiene abierta la misma biblioteca, las operaciones de escritura pueden fallar por el bloqueo de la base de datos; cierra Calibre antes de importar.