Calibre MCP

Un servidor de solo lectura del Model Context Protocol para una biblioteca de libros electrónicos Calibre existente.

Calibre MCP permite a los clientes compatibles con MCP buscar metadatos de libros, consultar el índice de texto completo de Calibre, inspeccionar los detalles de los libros, explorar las categorías de la biblioteca y descubrir libros relacionados. Utiliza la interfaz de línea de comandos calibredb compatible con Calibre en lugar de leer metadata.db directamente.

Características

• Búsqueda de metadatos mediante el lenguaje de búsqueda de Calibre

• Búsqueda de texto completo con fragmentos coincidentes

• Metadatos detallados de libros individuales

• Libros añadidos recientemente

• Autores, etiquetas, series, editoriales y categorías de idioma

• Descubrimiento de libros relacionados

• Recursos MCP para libros, búsquedas y estado de la biblioteca

• Enlaces opcionales al Calibre Content Server

• Caché TTL en memoria

• Transporte Streamable HTTP

• Despliegue con Podman Quadlet

• Sin herramientas MCP que modifiquen metadatos

Related MCP server: calibre-manager

Herramientas disponibles

Recursos MCP

Requisitos

• Una biblioteca de Calibre con metadata.db

• Calibre 9.x

• Python 3.11 o superior

• Un cliente MCP compatible con Streamable HTTP

• Podman y systemd para el despliegue Quadlet incluido

Las herramientas de texto completo requieren que el índice de texto completo de Calibre esté habilitado y completado.

Inicio rápido con Podman Quadlet

1. Clonar el repositorio

git clone https://github.com/monch1962/calibre-mcp.git
cd calibre-mcp

2. Confirmar tu biblioteca de Calibre

El Quadlet suministrado asume:

/tank/media/Books

Confirma que la base de datos de la biblioteca existe:

test -f /tank/media/Books/metadata.db && echo "Calibre library found"

3. Determinar el propietario de la biblioteca

stat -c 'uid=%u gid=%g owner=%U:%G' /tank/media/Books

Edita quadlet/calibre-mcp.container y establece User= con el UID y GID numéricos devueltos:

User=1000:1000

También cambia la ruta de la biblioteca del host si la tuya es diferente:

Volume=/tank/media/Books:/books

4. Construir la imagen

sudo podman build \
  --build-arg CALIBRE_VERSION=9.11.0 \
  -t localhost/calibre-mcp:1.0.0 .

5. Instalar el Quadlet

sudo mkdir -p /etc/containers/systemd

sudo cp quadlet/calibre-mcp.container \
  /etc/containers/systemd/calibre-mcp.container

sudo systemctl daemon-reload
sudo systemctl start calibre-mcp.service

No ejecutes systemctl enable calibre-mcp.service. El servicio generado es transitorio; la sección [Install] del Quadlet crea la dependencia de arranque.

6. Verificar el despliegue

sudo systemctl status calibre-mcp.service --no-pager
sudo journalctl -u calibre-mcp.service -n 100 --no-pager
sudo podman ps --filter name=calibre-mcp

Verifica Calibre dentro del contenedor:

sudo podman exec calibre-mcp \
  calibredb list \
  --with-library /books \
  --for-machine \
  --fields title \
  --limit 1

sudo podman exec calibre-mcp \
  calibredb fts_index status \
  --with-library /books

El endpoint predeterminado es:

http://localhost:8008/mcp

Probar con MCP Inspector

npx @modelcontextprotocol/inspector

Selecciona Streamable HTTP y conéctate a:

http://YOUR_SERVER:8008/mcp

Ejemplo de búsqueda de metadatos:

{
  "query": "author:asimov",
  "limit": 10
}

Ejemplo de búsqueda de texto completo:

{
  "query": "zero trust architecture",
  "limit": 10
}

Ejemplo de búsqueda de texto completo restringida:

{
  "query": "encryption",
  "limit": 10,
  "restrict_to": "search:tags:security"
}

Conectar un cliente MCP

Usa el endpoint Streamable HTTP expuesto por el servidor:

http://YOUR_SERVER:8008/mcp

Los formatos de configuración del cliente varían. Consulta la documentación MCP de tu cliente y selecciona Streamable HTTP en lugar de stdio o SSE heredado.

Ejemplos de búsqueda en Calibre

search_books acepta expresiones de búsqueda de Calibre:

author:asimov
title:"i robot"
tags:history
series:"Discworld"
publisher:penguin
languages:eng
rating:>=4

Una consulta vacía devuelve todos los libros, sujeto al límite de resultados.

Enlaces opcionales al Content Server

Establece la URL de tu Calibre Content Server existente en el Quadlet:

Environment=CALIBRE_CONTENT_SERVER_URL=http://mini-nas:8083

Cuando está configurado, los resultados de metadatos incluyen enlaces de navegador y de descarga de formatos.

Configuración

Por qué el montaje de la biblioteca es escribible

Calibre comprueba si el sistema de archivos de la biblioteca distingue entre mayúsculas y minúsculas creando y eliminando brevemente un archivo de prueba en la raíz de la biblioteca. En consecuencia, el montaje bind no puede montarse como solo lectura.

Este servidor sigue siendo funcionalmente de solo lectura porque no expone herramientas que llamen a comandos de Calibre como:

• add

• remove

• set_metadata

• add_format

• remove_format

Ejecuta el contenedor con el mismo UID y GID sin privilegios que poseen la biblioteca. No lo ejecutes como root a menos que tu entorno lo requiera específicamente.

Seguridad

• Mantén el puerto 8008 restringido a clientes de LAN o Tailscale de confianza.

• No expongas el endpoint directamente a Internet público.

• Streamable HTTP no añade autenticación en este despliegue.

• Coloca un proxy inverso autenticado delante del servicio antes de una exposición más amplia.

• Fija versiones de lanzamiento en lugar de usar una etiqueta de contenedor móvil.

• Revisa SECURITY.md antes de informar de una vulnerabilidad.

Endurecimiento del equipo rojo (ronda 1)

Se demostraron diez vectores de ataque adversarios con pruebas fallidas y luego se corrigieron. Cada prueba TestAttack_* en tests/attack_round1_test.py es un dispositivo de regresión permanente para su vector.

Superficies conocidas como seguras verificadas en esta ronda: inyección de shell (lista argv, sin shell=True), inyección de valores de opción (--sort-by/--categories/--restrict-to rechazan valores con guion inicial en el analizador de Calibre), traversal de rutas en URI de recursos (los IDs no numéricos se rechazan), limitación de resultados (_limit) y condiciones de carrera en la caché (protegida con bloqueo).

Endurecimiento del equipo rojo (ronda 2)

Se demostraron y corrigieron seis vectores de validación de forma de entrada; dispositivos en tests/attack_round2_test.py.

Endurecimiento del red team (ronda 3)

Tres vectores de robustez en rutas de error probados y corregidos; fixtures en tests/attack_round3_test.py.

Endurecimiento del red team (ronda 4)

Dos vectores de concurrencia/inundación de procesos probados y corregidos; fixtures en tests/attack_round4_test.py.

Endurecimiento del red team (ronda 5 — verificación final)

Cero vulnerabilidades nuevas. Una auditoría de brechas de cobertura añadió 11 pruebas de verificación (tests/attack_round5_test.py) que ejercitan todos los puntos de entrada aún no cubiertos por las rondas 1–4 — search_resource, book_resource (no numérico, tipo traversal, dentro de rango), status_resource, library_status, list_recent_books, clear_cache, payloads de lista de search_fulltext, límites cero/negativos, TTL cero desactivación de caché y consultas de solo espacios en blanco. Todas pasaron de inmediato, confirmando que las defensas de las rondas 1–4 se mantienen en toda la superficie de herramientas/recursos.

Se registraron dos hallazgos de documentación sobre la postura de despliegue en SECURITY.md (sin cambios de código): el Containerfile no tiene directiva USER (se ejecuta como root cuando se construye fuera del Quadlet, que establece User=1000:1000), y el Quadlet establece SecurityLabelDisable=true (la separación de etiquetas SELinux está desactivada).

Desarrollo local

Crea un entorno virtual:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest ruff

Ejecuta las pruebas:

pytest

Ejecuta las comprobaciones de lint:

ruff check .

Inicia el servidor localmente:

export CALIBRE_LIBRARY_PATH="/path/to/Calibre Library"
python server.py

Estado del proyecto

La versión 1.0.0 es adecuada para despliegues personales y en redes de confianza. La API pública puede incorporar herramientas y recursos adicionales en futuras versiones menores, mientras que los nombres de herramientas y las formas de los argumentos existentes se mantendrán estables siempre que sea práctico.

Contribuciones

Las issues y las pull requests son bienvenidas. Consulta CONTRIBUTING.md.

Licencia

Publicado bajo la Licencia MIT.