Calibre

calibre-mcp

Um servidor Model Context Protocol (MCP) para pesquisar e ler livros da sua biblioteca de ebooks do Calibre.

Recursos

• Pesquisa de texto completo com correspondência automática de frases e fallback difuso
• Pesquisa por autor ou título com correspondência parcial
• Extrair trechos de texto de livros com destaque de palavras-chave e paginação
• Implementação pura em bash usando a CLI do calibredb
• Retorna deep links do Calibre (calibre://) e URLs de arquivo (file://)
• Tratamento robusto de timeout para compatibilidade com macOS

Pré-requisitos

• Calibre instalado em /Applications/calibre.app
• Uma biblioteca do Calibre em ~/Calibre Library
• Exportações em texto (.txt) dos seus livros para a funcionalidade de trechos
• Bash 4.0 ou posterior

Instalação

1. Clone este repositório:

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

2. Torne o script executável:

chmod +x calibre-mcp.sh

Uso

Com o MCP Inspector

Teste o servidor usando o MCP Inspector:

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

Com o Claude Desktop

Adicione à configuração do seu Claude Desktop:

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

Ferramentas Disponíveis

search-fulltext

Pesquisa livros usando o mecanismo de pesquisa de texto completo do Calibre.

Parâmetros:

• query (obrigatório): Consulta de pesquisa. Consultas com várias palavras são automaticamente pesquisadas como frases
• limit (opcional): Máximo de resultados (padrão: 50)
• fuzzy_fallback (opcional): Consulta de fallback com termos relacionados se a pesquisa exata falhar

Exemplo:

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

search-author

Pesquisa livros pelo nome do autor com correspondência parcial.

Parâmetros:

• author (obrigatório): Nome do autor (correspondência parcial suportada)
• limit (opcional): Máximo de resultados (padrão: 50)

search-title

Pesquisa livros pelo título com correspondência parcial.

Parâmetros:

• title (obrigatório): Título do livro (correspondência parcial suportada)
• limit (opcional): Máximo de resultados (padrão: 50)

get-excerpt

Extrai trechos de texto de livros com contexto de palavras-chave.

Parâmetros:

• book_id (obrigatório): ID do livro no Calibre
• keyword (opcional): Termo de pesquisa para encontrar no livro
• context_lines (opcional): Linhas de contexto ao redor das correspondências (padrão: 10)
• max_results (opcional): Resultados por página (padrão: 10)
• page (opcional): Número da página para paginação (padrão: 1)

Formato de Resposta

Os resultados da pesquisa incluem:

• Metadados do livro (título, autores, série, tags, editora)
• Deep link do Calibre para abrir no Calibre
• URL do arquivo para acesso direto ao EPUB
• Formatos disponíveis
• Se o formato de texto está disponível para trechos

Registro de Logs

O servidor registra todas as solicitações e respostas em requests.log para depuração.

Limitações

• Requer que o Calibre esteja fechado ou pode haver timeouts
• A pesquisa de texto completo requer livros indexados
• A extração de trechos funciona apenas com exportações .txt

Licença

Apache License 2.0 - Consulte o arquivo LICENSE para detalhes.