calibre-mcp

Calibre 전자책 라이브러리를 검색, 읽기 및 관리하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. Bun을 위해 TypeScript로 완전히 재작성되었으며, 초고속 성능, Calibre CLI 도구와의 심층적인 통합, 자동화된 콘텐츠 추출 기능을 제공합니다.

🚀 기능

• 초고속 메타데이터 검색: SQLite를 통해 Calibre의 metadata.db를 직접 쿼리하여 거의 즉각적인 결과를 제공합니다.

• 전문(Full-text) 콘텐츠 검색: Calibre의 색인된 전문 검색 엔진을 활용하여 라이브러리 전체에서 특정 문구를 찾습니다.

• 동적 콘텐츠 추출: EPUB, PDF 및 기타 형식을 즉석에서 텍스트로 자동 변환합니다. 수동으로 .txt 파일을 내보낼 필요가 없습니다.

• 포괄적인 라이브러리 관리: 데이터베이스 메타데이터 업데이트, 내부 파일 메타데이터 수정, 책 다듬기(polish), 형식 간 변환을 수행합니다.

• 스마트 결과 배분: 검색 결과가 여러 책에 걸쳐 지능적으로 균형을 이루어 다양한 일치 항목을 제공합니다.

• 사용자 지정 URL 스키마: 책 위치와 줄 범위를 정확하게 참조하기 위해 epub:// URL을 사용합니다.

Related MCP server: Calibre RAG MCP Server

📋 필수 조건

• /Applications/calibre.app(macOS)에 설치된 Calibre.

• 설치된 Bun 런타임.

• Calibre 라이브러리.

⚙️ 구성

이 서버는 다음 환경 변수를 사용합니다:

• CALIBRE_LIBRARY_PATH: Calibre 라이브러리 경로(metadata.db가 있는 곳). 기본값은 /Volumes/Xarismata/eBooks/CalibreNuevo입니다.

🛠 설치

1. 이 저장소를 복제합니다:

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

2. 의존성을 설치합니다:

bun install

⌨️ 사용법

MCP Inspector 사용

대화형 환경에서 서버를 테스트합니다:

npx @modelcontextprotocol/inspector bun src/index.ts

Claude Desktop 사용

claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "calibre": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/calibre-mcp/src/index.ts"]
    }
  }
}

🧰 사용 가능한 도구

도구 세부 정보 및 예시

search_library

콘텐츠에 대한 자연어 검색이나 메타데이터의 특정 필드를 사용하여 검색합니다.

• 쿼리 예시:

  • "machine learning" (전문 검색)

  • author:Asimov title:Foundation (메타데이터 검색)

  • tag:science-fiction rating:>4 (고급 필터링)

read_content

epub:// 스키마를 사용합니다.

• 형식: epub://[저자]/[제목]@[책_ID]#[시작_줄]:[끝_줄]

• 예시: epub://Isaac%20Asimov/Foundation@123#500:600은 500번째 줄부터 600번째 줄까지를 가져옵니다.

polish_book

자동 변환된 파일이나 오래된 파일을 정리하는 데 적합합니다.

• 옵션: smartenPunctuation, compressImages, upgradeBook, removeUnusedCss.

convert_ebook

형식을 변환하고 라이브러리 기록을 자동으로 업데이트합니다.

• 예시: book_id: 45, output_format: "azw3", options: ["--enable-heuristics"]

deep_search_book

특정 책 내부를 직접 검색합니다(Calibre FTS가 아직 색인하지 않은 경우 유용).

• 예시: book_id: 123, query: "quantum entanglement", context_lines: 3

⚖️ 라이선스

Apache License 2.0 - 자세한 내용은 LICENSE 파일을 참조하세요.