calibre-mcp

로컬 MCP 서버(stdio)로, LLM 호스트(Claude Desktop, Claude Code 또는 MCP 호환 클라이언트)가 Calibre 전자책 라이브러리를 대화형으로 관리할 수 있게 해줍니다: 검색, 메타데이터 편집, 추가, 변환, 중복 제거, 삭제, 이메일 전송 — 모두 인간 개입 안전장치와 함께 제공됩니다.

**대부분의 Calibre MCP 서버는 읽기 전용입니다 — 검색하고 나열만 합니다. 이 서버는 쓰기를 수행하며, 안전하게 수행합니다.** 메타데이터 편집, 추가, 변환, 삭제는 도구가 실제로 라이브러리를 손상시키거나 잃어버릴 수 있는 작업입니다. 따라서 모든 변경 작업은 우발적으로 발생할 수 없도록 설계된 구조를 거칩니다:

• 모든 파괴적 작업에 대해 계획 → 확인. 첫 번째 호출은 사람이 읽을 수 있는 diff와 confirmation_token을 반환합니다. 정확한 토큰으로 다시 호출하기 전에는 아무것도 변경되지 않습니다.

• 모든 쓰기 전에 자동 metadata.db 백업(롤링, 최근 20개).

• 복구 가능한 삭제 — 휴지통 복사본 및 Calibre 재활용 폴더, 영구 삭제는 없음.

• 읽기는 아무것도 손상시킬 수 없음 — SQLite 연결은 mode=ro로 열립니다.

Calibre GUI를 클릭하는 대신 채팅으로 라이브러리를 관리하기 위해 만들어졌으며, 사용자의 파일을 삭제할 수 있는 도구를 설계하는 방법을 보여주는 쇼케이스로 의도적으로 설계되었습니다: 하이브리드 I/O 설계, 명시적 오류 분류 체계, 모든 파괴적 작업에 대한 인간 승인 게이트, 그리고 실제 사용자 데이터를 절대 건드리지 않는 테스트 스위트. 무엇을 하는지와 이유는 PRODUCT.md를, 전체 설계 문서는 ARCHITECTURE.md를 참조하세요.

하이브리드 설계의 이유

• 읽기(search, list, view, 중복 찾기)는 metadata.db를 직접 읽기 전용으로 쿼리합니다 — 빠르고, 구조적으로 라이브러리를 손상시킬 수 없습니다(SQLite 연결은 mode=ro로 열림).

• 쓰기(edit, add, remove, convert, email)는 Calibre의 자체 CLI 도구(calibredb, ebook-convert, calibre-smtp)를 통해 수행됩니다 — 원시 SQL은 절대 사용하지 않으므로 Calibre가 자체 데이터베이스에 대한 권위를 유지합니다.

• 모든 쓰기 전에 자동 metadata.db 백업(롤링, 최근 20개 유지)이 수행됩니다.

• 삭제는 복구 가능합니다: 파일은 관리되는 휴지통 폴더로 복사되고 또한 책은 Calibre의 재활용 폴더로 이동됩니다 — 영구 삭제는 없습니다.

• 모든 변경 또는 외부 전송 도구는 2단계(계획 → 확인)입니다: 첫 번째 호출은 사람이 읽을 수 있는 검토와 confirmation_token을 반환합니다. 정확한 토큰으로 다시 호출하기 전에는 아무것도 변경되지 않고 아무것도 전송되지 않습니다.

이러한 선택에 대한 전체 근거, 모듈 경계, 결정 로그는 ARCHITECTURE.md에 있습니다.

Related MCP server: calibre-mcp

요구 사항

• Calibre 설치, calibredb와 ebook-convert가 PATH에 있어야 함(calibredb --version). email_book을 사용하려면 calibre-smtp도 필요합니다.

• Python ≥ 3.12 및 uv.

설치

클론 없이(권장) — uv가 저장소에서 직접 빌드하고 실행합니다. 수동 체크아웃이 필요 없습니다:

uvx --from git+https://github.com/gustavofsousa/calibre-mcp calibre-mcp

로컬 체크아웃에서(개발용 또는 특정 상태를 고정하려는 경우):

git clone https://github.com/gustavofsousa/calibre-mcp calibre-mcp
cd calibre-mcp
uv sync

구성

서버는 하나의 라이브러리를 관리하며, 환경 변수로 설정합니다:

서버는 CALIBRE_LIBRARY_PATH가 설정되지 않았거나 디렉토리에 metadata.db가 없으면 시작 시 명확한 오류와 함께 빠르게 실패합니다.

email_book은 추가로 SMTP 릴레이 자격 증명이 필요합니다(지연 로드됨 — 서버는 자격 증명 없이도 정상적으로 부팅되며, 누락된 경우 email_book만 실패합니다):

Claude Desktop / Claude Code

MCP 구성(예: claude_desktop_config.json)에 추가하세요. 클론 없이 — uvx를 통해 저장소에서 직접 실행:

{
  "mcpServers": {
    "calibre": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gustavofsousa/calibre-mcp", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

또는 로컬 체크아웃에서:

{
  "mcpServers": {
    "calibre": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/calibre-mcp", "run", "calibre-mcp"],
      "env": {
        "CALIBRE_LIBRARY_PATH": "/absolute/path/to/your/Calibre Library"
      }
    }
  }
}

수동 실행

CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run calibre-mcp
# or equivalently:
CALIBRE_LIBRARY_PATH="/path/to/Calibre Library" uv run python -m calibre_mcp

서버는 stdio(JSON-RPC)로 통신합니다. MCP 프레임 외에는 stdout에 아무것도 출력하지 않습니다 — 모든 로그는 의도적으로 stderr로 보냅니다(ARCHITECTURE.md 참조).

도구

또한 하나의 MCP 리소스, calibre://library/stats — 도구 호출 없이 읽을 수 있는 집계 라이브러리 프로필(총계, 형식/언어 혼합, 메타데이터 완전성, 데이터 품질 플래그)이 있습니다.

모든 도구의 전체 계약(엣지 케이스, 오류 조건, 정확한 필드 허용 목록)은 server.py의 docstring에 문서화되어 있습니다 — 이 docstring은 LLM 호스트가 보는 내용이므로 API 참조 역할을 겸합니다.

개발

uv run ruff check src tests   # lint
uv run pytest                 # full suite (unit + integration + e2e)
uv run pytest -m unit         # fast unit tests only

세 계층(unit, integration, e2e)에 걸친 137개의 테스트; 쓰기 테스트는 실제 라이브러리를 건드리지 않습니다 — ARCHITECTURE.md 참조.

프로젝트 구조

src/calibre_mcp/
├── server.py               # FastMCP tool surface — the only stdio/MCP-aware module
├── library.py               # CalibreLibrary facade — orchestrates every tool's business logic
├── sqlite_reader.py         # Read-only metadata.db access (the only sqlite3 call site)
├── calibredb_runner.py      # calibredb subprocess wrapper (search/edit/add/remove/add_format)
├── ebook_convert_runner.py  # ebook-convert subprocess wrapper
├── calibre_smtp_runner.py   # calibre-smtp subprocess wrapper
├── backup.py                 # metadata.db snapshots + recoverable trash
├── confirmation.py           # plan→confirm token derivation/verification
├── config.py                  # env-driven startup config, fail-fast validation
└── errors.py                  # the failure taxonomy every layer maps to

로드맵

출시됨: 전체 읽기/정리/배포 루프(검색, 목록, 보기, 편집, 추가, 삭제, 변환, 중복 제거, 이메일). 다음 단계 — 라이브러리 자체 지식, 대량 작업, 표지/메타데이터 강화, 기기 동기화 — 는 .specs/ROADMAP.md에 추적되어 있으며, 순서 결정 이유와 명시적으로 범위를 벗어난 항목도 포함됩니다.

기여

개발 워크플로, PR이 유지해야 하는 불변 조건, 이 저장소 뒤에 있는 사양 기반 프로세스에 대해서는 CONTRIBUTING.md를 참조하세요.

라이선스

MIT © Gustavo F Sousa.