calibreweb-mcp

Un servidor de solo lectura del Model Context Protocol para Calibre-Web (y Calibre-Web Automated), la interfaz web autohospedada de bibliotecas de libros electrónicos.

Calibre-Web no tiene una API REST; su única interfaz estable legible por máquina es el feed del catálogo OPDS que sirve para aplicaciones de lectura de libros electrónicos. Este servidor habla ese feed: XML Atom con autenticación HTTP Basic de entrada, datos estructurados de libros de salida. Busca en la biblioteca, navega por las vistas y estanterías seleccionadas, sigue enlaces de descarga por formato y obtén imágenes de portada directamente en la conversación. Nunca escribe nada: cada herramienta es una petición GET a las rutas OPDS.

📖 Documentación completa: calibreweb-mcp.ni-c.de

Requisitos

• Node.js 22 o superior

• Una instancia de Calibre-Web (desarrollada contra la imagen actual linuxserver/calibre-web; Calibre-Web Automated funciona de la misma manera)

• Un usuario de Calibre-Web para el servidor. El feed OPDS se autentica con el inicio de sesión web normal: usa una cuenta dedicada con solo los roles de Ver y Descargar, no tu cuenta de administrador. Si la instancia permite la navegación anónima, el servidor también puede ejecutarse sin credenciales.

Related MCP server: access-calibre

Configuración

¹ Deja ambos sin establecer para una instancia que permita navegación anónima; establecer solo uno de ellos es un error de configuración.

Claude Code

claude mcp add calibreweb \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  -- npx calibreweb-mcp

Claude Desktop

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["calibreweb-mcp"],
      "env": {
        "CALIBRE_WEB_URL": "https://books.example.com",
        "CALIBRE_WEB_USERNAME": "reader",
        "CALIBRE_WEB_PASSWORD": "..."
      }
    }
  }
}

Codex

[mcp_servers.calibreweb]
command = "npx"
args = ["calibreweb-mcp"]
env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }

Herramientas

Todas las herramientas son de solo lectura (readOnlyHint: true).

Las entradas de libros incluyen autores, etiquetas, serie (con índice), valoración, un resumen acotado, una URL de portada y URLs de descarga por formato — enlaces listos para que un humano los abra, ya que el modelo en sí no tiene razón para descargar un EPUB.

Paginación

Los feeds se paginan según la configuración de libros por página de la instancia (por defecto 60); el tamaño de página no es controlable por el cliente. Cada listado devuelve pagination.nextOffset cuando existen más páginas — pásalo como offset en la siguiente llamada. La vista discover es una selección aleatoria y no está paginada.

Deliberadamente fuera del alcance

• Sin escrituras. El feed OPDS no tiene ninguna, y este servidor no añadiría ninguna.

• Sin descargas de archivos. Las herramientas devuelven URLs de descarga, no los archivos de los libros electrónicos.

• Sin navegación por facetas (autores/series/etiquetas/editoriales/idiomas/formatos como sus propios feeds de índice). search_books cubre esas búsquedas; las rutas existen y se pueden añadir herramientas para ellas si hay un caso de uso real.

Seguridad

• El servidor es de solo lectura por construcción — solo peticiones GET, sin estado en ninguna parte.

• Los metadatos de los libros son datos de terceros no confiables; cada resultado lo indica, se eliminan los caracteres de control y se deshabilita el procesamiento de entidades XML (los documentos que declaran un DOCTYPE o entidades son rechazados de plano).

• Las respuestas están limitadas antes de analizarlas (8 MB de feeds, 1 MB de portadas) y nuevamente antes de que lleguen al modelo (presupuestos por libro y por respuesta).

• Los hrefs del feed solo se transmiten cuando se resuelven al origen configurado a través de http(s) — un feed hostil no puede insertar URLs javascript:, file: o de origen cruzado en los resultados.

• Se rechazan las redirecciones para que las credenciales Basic nunca se puedan reutilizar en otro host; las portadas solo se transmiten para tipos de contenido de imagen reales.

• La contraseña se elimina del entorno del proceso al inicio, y las URLs se redactan de credenciales antes de aparecer en cualquier registro o resultado.

Contenedor

docker run -i --rm \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  ghcr.io/ni-c/calibreweb-mcp

Desarrollo

npm install
npm test            # unit tests against a stubbed OPDS feed, no instance needed
npm run lint
npm run build

Ver CONTRIBUTING.md.

Publicación

1. Actualiza CHANGELOG.md y aumenta la versión en package.json (+ archivo de bloqueo).

2. npm run lint && npm run test:coverage && npm run build

3. Etiqueta la publicación: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

Licencia

MIT