Calibre

calibre-mcp

Un servidor de Model Context Protocol (MCP) para buscar y leer libros de tu biblioteca electrónica de Calibre.

Características

• Búsqueda de texto completo con coincidencia automática de frases y respaldo difuso
• Búsqueda por autor o título con coincidencia parcial
• Extracción de extractos de texto de libros con resaltado de palabras clave y paginación
• Implementación pura en bash usando calibredb CLI
• Devuelve enlaces profundos de Calibre (calibre://) y URLs de archivos (file://)
• Manejo robusto de tiempos de espera para compatibilidad con macOS

Requisitos previos

• Calibre instalado en /Applications/calibre.app
• Una biblioteca de Calibre en ~/Calibre Library
• Exportaciones de texto (.txt) de tus libros para la funcionalidad de extractos
• Bash 4.0 o posterior

Instalación

1. Clona este repositorio:

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

2. Haz ejecutable el script:

chmod +x calibre-mcp.sh

Uso

Con MCP Inspector

Prueba el servidor usando el MCP Inspector:

npx @modelcontextprotocol/inspector /path/to/calibre-mcp.sh

Con Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "calibre": {
      "command": "/path/to/calibre-mcp.sh"
    }
  }
}

Herramientas disponibles

search-fulltext

Busca libros usando el motor de búsqueda de texto completo de Calibre.

Parámetros:

• query (obligatorio): Consulta de búsqueda. Las consultas de varias palabras se buscan automáticamente como frases
• limit (opcional): Máximo de resultados (predeterminado: 50)
• fuzzy_fallback (opcional): Consulta de respaldo con términos relacionados si la búsqueda exacta falla

Ejemplo:

{
  "query": "machine learning",
  "fuzzy_fallback": "AI artificial intelligence ML neural networks deep learning"
}

search-author

Busca libros por nombre de autor con coincidencia parcial.

Parámetros:

• author (obligatorio): Nombre del autor (se admite coincidencia parcial)
• limit (opcional): Máximo de resultados (predeterminado: 50)

search-title

Busca libros por título con coincidencia parcial.

Parámetros:

• title (obligatorio): Título del libro (se admite coincidencia parcial)
• limit (opcional): Máximo de resultados (predeterminado: 50)

get-excerpt

Extrae extractos de texto de libros con contexto de palabras clave.

Parámetros:

• book_id (obligatorio): ID del libro en Calibre
• keyword (opcional): Término de búsqueda para encontrar en el libro
• context_lines (opcional): Líneas de contexto alrededor de las coincidencias (predeterminado: 10)
• max_results (opcional): Resultados por página (predeterminado: 10)
• page (opcional): Número de página para paginación (predeterminado: 1)

Formato de respuesta

Los resultados de búsqueda incluyen:

• Metadatos del libro (título, autores, serie, etiquetas, editorial)
• Enlace profundo de Calibre para abrir en Calibre
• URL del archivo para acceso directo a EPUB
• Formatos disponibles
• Si el formato de texto está disponible para extractos

Registro

El servidor registra todas las solicitudes y respuestas en requests.log para depuración.

Limitaciones

• Requiere que Calibre esté cerrado o puede experimentar tiempos de espera
• La búsqueda de texto completo requiere libros indexados
• La extracción de extractos solo funciona con exportaciones .txt

Licencia

Apache License 2.0 - Consulta el archivo LICENSE para más detalles.