calibre-mcp

로컬 Calibre 전자책 라이브러리에 대한 읽기/쓰기 액세스를 AI 어시스턴트(Claude Code, Claude Desktop, Cursor 등)에 제공하는 MCP 서버입니다.

라이브러리 검색, 최근 추가 항목 찾아보기, 자동 중복 감지와 함께 새 전자책 가져오기, "드롭 폴더" 받은 편지함 관리까지 — 모두 채팅으로 처리하세요.

• 일반적인 설정에서 구성 불필요: calibredb 실행 파일과 Calibre GUI가 사용하는 라이브러리는 macOS, Windows, Linux에서 자동으로 감지됩니다.

• 로케일 독립적: 모든 읽기는 calibredb --for-machine(JSON)을 거치므로 결과가 Calibre 인터페이스 언어에 의존하지 않습니다.

• 기본적으로 안전: 중복 감지는 Calibre 자체에 의존합니다. 제목+저자가 이미 라이브러리에 있는 책은 건너뛰고 두 번 가져오지 않습니다.

도구

Related MCP server: Calibre MCP Server

요구 사항

• Calibre(calibredb를 제공하는 모든 버전, 9.x로 테스트됨)

• Python ≥ 3.10

설치

pipx(권장)

pipx install calibre-mcp

uv

uv tool install calibre-mcp

pip

pip install calibre-mcp

소스에서

git clone https://github.com/ZehuiTIAN/calibre-mcp.git
cd calibre-mcp
pip install -e ".[dev]"     # dev extras add pytest + ruff

구성

일반적인 설정에서는 모든 것이 선택 사항입니다. 각 값은 환경 변수로 고정할 수 있습니다.

Claude Code에 등록

claude mcp add calibre-mcp -- calibre-mcp

또는 ~/.claude.json → mcpServers(사용자 범위)에 추가:

"calibre_mcp": {
  "type": "stdio",
  "command": "calibre-mcp",
  "args": [],
  "env": {
    "CALIBRE_LIBRARY_PATH": "/path/to/your/library",
    "CALIBRE_INBOX_DIR": "/path/to/your/inbox"
  }
}

Claude Desktop / Cursor에 등록

claude_desktop_config.json(Claude Desktop) 또는 Cursor의 MCP 설정에 있는 MCP 서버 섹션에 동일한 JSON 블록을 추가하세요.

받은 편지함 워크플로

드롭 폴더는 손으로 다운로드한 책에 대해 "찾기 → 놓기 → 보관" 루프를 만들어 줍니다.

1. CALIBRE_INBOX_DIR을 폴더(예: ~/Downloads/Calibre-Inbox)로 지정합니다.

2. 해당 폴더에 전자책을 다운로드합니다.

3. 어시스턴트에게 import_inbox를 실행하도록 요청합니다.

모든 파일이 라이브러리에 추가됩니다. 성공적으로 추가된 파일과 중복 파일은 imported/YYYY-MM/ 아래에, 실패한 파일은 failed/ 아래에 정리됩니다. 받은 편지함 자체는 깨끗하게 유지되며 어떤 것도 덮어쓰지 않습니다(이름 충돌 시 -1, -2, ... 접미사가 붙습니다).

지원 확장자: .epub .pdf .mobi .azw .azw3 .djvu .cbz .cbr .fb2 .txt .md .docx .rtf .lit .prc .pdb .chm .htmlz.

주의 사항

• 데이터베이스 잠금: Calibre GUI가 라이브러리를 열어 둔 동안에는 쓰기 작업(add_books, import_inbox)이 데이터베이스 잠금 오류로 실패할 수 있습니다. 읽기 전용 도구는 계속 작동합니다. 가져오기 전에 Calibre를 닫거나(또는 다른 라이브러리로 전환) 하세요.

• 대용량 라이브러리: add_books/import_inbox는 각 추가 전에 전체 책 ID 집합의 스냅샷을 만듭니다. 실제로는 빠르지만 가져오기당 책 수에 비례하는 O(책 수)입니다.

• 이 도구는 여러분의 라이브러리만 정리합니다. 검색이나 다운로드 기능은 포함되어 있지 않습니다. 보유할 권리가 있는 콘텐츠에 사용하세요.

개발

pip install -e ".[dev]"
ruff check .
pytest -m "not integration"      # unit tests, run anywhere
pytest                           # + integration tests (need local calibre)

통합 테스트는 /tmp 아래에 임시 라이브러리를 만들고 실제 라이브러리는 건드리지 않습니다.

라이선스

MIT — LICENSE를 참조하세요.

중국어 요약

로컬 Calibre 라이브러리를 Claude/Cursor 등의 AI 어시스턴트에 연결하는 MCP 서버: 다 가지 도구(library_info / search_books / list_books / add_books / import_inbox), calibredb와 라이브러리 위치 자동 감지, 전 플랫폼(Windows/macOS/Linux)에서 바로 사용 가능.

pipx install calibre-mcp
claude mcp add calibre-mcp -- calibre-mcp

가져올 때 자동 중복 검사(제목+저자가 같은 책은 중복 가져오지 않음); CALIBRE_INBOX_DIR 받은 편지함 디렉터리와 함께 사용하면 다운로드한 책을 넣고 "받은 편지함 가져오기"라고 말하면 아카이브되며, 처리된 파일은 자동으로 imported/ 또는 failed/로 분류됩니다.

참고: Calibre 데스크톱 프로그램이 같은 라이브러리를 열어 두면 데이터베이스 잠금으로 인해 쓰기 작업이 실패할 수 있으므로, 가져오기 전에 Calibre를 먼저 닫으세요.