calibre-mcp

Un servidor MCP local (stdio) que permite que un host de LLM — Claude Desktop, Claude Code o cualquier cliente compatible con MCP — gestione una biblioteca de libros electrónicos de Calibre de forma conversacional: buscar, editar metadatos, añadir, convertir, deduplicar, eliminar y enviar libros por correo, todo con seguridad de intervención humana.

La mayoría de los servidores MCP de Calibre son de solo lectura: buscan y listan. Este escribe — y lo hace de forma segura. Editar metadatos, añadir, convertir y eliminar libros es donde una herramienta puede realmente corromper o perder tu biblioteca, por lo que cada mutación aquí pasa por un diseño construido para que eso sea imposible de hacer por accidente:

• Plan → confirmar en cada acción destructiva. La primera llamada devuelve un diff legible por humanos y un confirmation_token; nada cambia hasta que vuelvas a llamar con ese token exacto.

• Copia de seguridad automática de metadata.db antes de cada escritura (rotativa, últimas 20).

• Eliminaciones recuperables — copia en papelera y papelera de reciclaje de Calibre, nunca una eliminación definitiva.

• Las lecturas no pueden corromper nada — la conexión SQLite se abre con mode=ro.

Construido para dejar de hacer clic en la interfaz gráfica de Calibre y gestionar una biblioteca desde un chat — y deliberadamente diseñado como una muestra de cómo diseñar una herramienta que tiene permiso para eliminar los archivos del usuario: diseño híbrido de E/S, una taxonomía explícita de fallos, compuertas de aprobación humana en cada acción destructiva y una suite de pruebas que nunca toca datos reales del usuario. Consulta PRODUCT.md para saber qué hace y por qué, y ARCHITECTURE.md para el documento de diseño completo.

Por qué el diseño híbrido

• Lecturas (search, list, view, búsqueda de duplicados) consultan metadata.db directamente, en modo solo lectura — rápido y estructuralmente incapaz de corromper la biblioteca (la conexión SQLite se abre con mode=ro).

• Escrituras (edit, add, remove, convert, email) pasan por las herramientas CLI de Calibre (calibredb, ebook-convert, calibre-smtp) — nunca SQL crudo — para que Calibre siga siendo la autoridad sobre su propia base de datos.

• Cada escritura va precedida de una copia de seguridad automática de metadata.db (rotativa, conserva las últimas 20).

• La eliminación es recuperable: los archivos se copian a una carpeta de papelera gestionada y el libro se envía a la papelera de reciclaje de Calibre — nunca una eliminación permanente.

• Cada herramienta que muta o se orienta hacia afuera es de dos pasos (plan → confirmar): la primera llamada devuelve una revisión legible por humanos más un confirmation_token; nada cambia — y nada se envía — hasta que vuelvas a llamar con ese token exacto.

La justificación completa, los límites de los módulos y el registro de decisiones detrás de estas elecciones están en ARCHITECTURE.md.

Related MCP server: calibre-mcp

Requisitos

• Calibre instalado, con calibredb y ebook-convert en tu PATH (calibredb --version). calibre-smtp también es necesario si quieres email_book.

• Python ≥ 3.12 y uv.

Instalación

Sin clonar (recomendado) — uv lo compila y ejecuta directamente desde el repositorio, sin clonado manual:

uvx --from git+https://github.com/gustavofsousa/calibre-mcp calibre-mcp

Desde un clon local (para desarrollo, o para fijar un estado específico):

git clone https://github.com/gustavofsousa/calibre-mcp calibre-mcp
cd calibre-mcp
uv sync

Configuración

El servidor gestiona una biblioteca, configurada mediante variable de entorno:

El servidor falla rápidamente al inicio con un error claro si CALIBRE_LIBRARY_PATH no está definida o el directorio no tiene metadata.db.

email_book además necesita credenciales de relay SMTP (se cargan de forma diferida — el servidor arranca sin problemas sin ellas, y solo email_book falla si faltan):

Claude Desktop / Claude Code

Añade a tu configuración de MCP (p. ej. claude_desktop_config.json). Sin clonar — se ejecuta directamente desde el repositorio mediante uvx:

{
  "mcpServers": {
    "calibre": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gustavofsousa/calibre-mcp", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

O, desde un clon local:

{
  "mcpServers": {
    "calibre": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/calibre-mcp", "run", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

Ejecución manual

CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run calibre-mcp
# or equivalently:
CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run python -m calibre_mcp

El servidor se comunica a través de stdio (JSON-RPC); no imprime nada en stdout excepto el marco de MCP — todos los registros van a stderr, a propósito (consulta ARCHITECTURE.md).

Herramientas

Además, un recurso MCP, calibre://library/stats — un perfil agregado de la biblioteca (totales, mezcla de formatos/idiomas, completitud de metadatos, indicadores de calidad de datos) legible sin ninguna llamada de herramienta.

El contrato completo de cada herramienta (casos límite, condiciones de error, lista blanca exacta de campos) está documentado en su docstring en server.py — esos docstrings son lo que ve el host de LLM, por lo que sirven también como referencia de la API.

Desarrollo

uv run ruff check src tests   # lint
uv run pytest                 # full suite (unit + integration + e2e)
uv run pytest -m unit         # fast unit tests only

137 pruebas en tres niveles (unit, integration, e2e); las pruebas de escritura nunca tocan una biblioteca real — consulta ARCHITECTURE.md.

Estructura del proyecto

src/calibre_mcp/
├── server.py               # FastMCP tool surface — the only stdio/MCP-aware module
├── library.py               # CalibreLibrary facade — orchestrates every tool's business logic
├── sqlite_reader.py         # Read-only metadata.db access (the only sqlite3 call site)
├── calibredb_runner.py      # calibredb subprocess wrapper (search/edit/add/remove/add_format)
├── ebook_convert_runner.py  # ebook-convert subprocess wrapper
├── calibre_smtp_runner.py   # calibre-smtp subprocess wrapper
├── backup.py                 # metadata.db snapshots + recoverable trash
├── confirmation.py           # plan→confirm token derivation/verification
├── config.py                  # env-driven startup config, fail-fast validation
└── errors.py                  # the failure taxonomy every layer maps to

Hoja de ruta

Entregado: bucle completo de lectura/gestión/distribución (búsqueda, listado, vista, edición, adición, eliminación, conversión, deduplicación, correo). Lo que viene — autoconocimiento de la biblioteca, operaciones masivas, enriquecimiento de portadas/metadatos, sincronización de dispositivos — se sigue en .specs/ROADMAP.md, incluida la justificación de la secuenciación y lo que está explícitamente fuera de alcance.

Contribuciones

Consulta CONTRIBUTING.md para el flujo de trabajo de desarrollo, los invariantes que una PR debe preservar y cómo funciona el proceso dirigido por especificaciones detrás de este repositorio.

Licencia

MIT © Gustavo F Sousa.