calibreweb-mcp

Calibre-Web(및 Calibre-Web Automated)용 읽기 전용 Model Context Protocol 서버입니다. Calibre-Web은 자체 호스팅 전자책 라이브러리 웹 UI입니다.

Calibre-Web에는 REST API가 없습니다. 유일하게 안정적인 기계 판독 가능 인터페이스는 전자책 리더 앱을 위해 제공하는 OPDS 카탈로그 피드입니다. 이 서버는 해당 피드를 처리합니다: Atom XML에 HTTP Basic 인증을 입력으로 받아 구조화된 책 데이터를 출력합니다. 라이브러리 검색, 큐레이팅된 보기 및 선반 탐색, 형식별 다운로드 링크 추적, 표지 이미지를 대화에 바로 가져올 수 있습니다. 쓰기 작업은 전혀 수행하지 않습니다. 모든 도구는 OPDS 경로에 대한 GET 요청입니다.

📖 전체 문서: calibreweb-mcp.ni-c.de

요구 사항

• Node.js 22 이상

• Calibre-Web 인스턴스(현재 linuxserver/calibre-web 이미지를 기준으로 개발됨; Calibre-Web Automated도 동일하게 작동)

• 서버용 Calibre-Web 사용자. OPDS 피드는 일반 웹 로그인으로 인증합니다. 관리자 계정이 아닌 보기 및 다운로드 권한만 있는 전용 계정을 사용하세요. 인스턴스에서 익명 탐색을 허용하는 경우 서버는 자격 증명 없이도 실행할 수 있습니다.

Related MCP server: access-calibre

설정

¹ 익명 탐색을 허용하는 인스턴스의 경우 둘 다 설정하지 않은 상태로 두세요. 하나만 설정하면 설정 오류입니다.

Claude Code

claude mcp add calibreweb \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  -- npx calibreweb-mcp

Claude Desktop

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["calibreweb-mcp"],
      "env": {
        "CALIBRE_WEB_URL": "https://books.example.com",
        "CALIBRE_WEB_USERNAME": "reader",
        "CALIBRE_WEB_PASSWORD": "..."
      }
    }
  }
}

Codex

[mcp_servers.calibreweb]
command = "npx"
args = ["calibreweb-mcp"]
env = { CALIBRE_WEB_URL = "https://books.example.com", CALIBRE_WEB_USERNAME = "reader", CALIBRE_WEB_PASSWORD = "..." }

도구

모든 도구는 읽기 전용입니다 (readOnlyHint: true).

책 항목에는 저자, 태그, 시리즈(인덱스 포함), 평점, 요약(길이 제한), 표지 URL 및 형식별 다운로드 URL이 포함됩니다. 모델 자체가 EPUB를 다운로드할 이유가 없으므로 사람이 열 수 있는 바로 사용 가능한 링크입니다.

페이지네이션

피드는 인스턴스의 페이지당 책 수 설정(기본값 60)에 따라 페이지가 매겨집니다. 페이지 크기는 클라이언트가 제어할 수 없습니다. 모든 목록은 더 많은 페이지가 있을 때 pagination.nextOffset을 반환합니다. 다음 호출에서 offset으로 전달하세요. discover 보기는 무작위 선택이며 페이지가 매겨지지 않습니다.

의도적으로 범위에서 제외된 사항

• 쓰기 작업 없음. OPDS 피드에는 쓰기 작업이 없으며, 이 서버도 추가하지 않습니다.

• 파일 다운로드 없음. 도구는 다운로드 URL을 반환하며, 전자책 페이로드는 반환하지 않습니다.

• 패싯 탐색 없음 (저자/시리즈/태그/출판사/언어/형식을 자체 인덱스 피드로 제공). search_books가 해당 조회를 처리합니다. 해당 경로는 존재하며 실제 사용 사례가 있을 경우 도구를 추가할 수 있습니다.

안전성

• 서버는 구조적으로 읽기 전용입니다. GET 요청만 수행하며, 상태를 저장하지 않습니다.

• 책 메타데이터는 신뢰할 수 없는 타사 데이터입니다. 모든 결과에 이를 명시하고, 제어 문자를 제거하며, XML 엔터티 처리를 비활성화합니다(DOCTYPE 또는 엔터티를 선언하는 문서는 완전히 거부).

• 응답은 구문 분석 전에 제한되고(8MB 피드, 1MB 표지), 모델에 도달하기 전에 다시 제한됩니다(책당 및 응답당 예산).

• 피드 href는 설정된 출처에 대해 http(s)로 확인되는 경우에만 전달됩니다. 악의적인 피드는 javascript:, file: 또는 교차 출처 URL을 결과에 심을 수 없습니다.

• 리디렉션은 거부되어 Basic 자격 증명이 다른 호스트로 재전송되지 않습니다. 표지는 실제 이미지 콘텐츠 유형에 대해서만 전달됩니다.

• 비밀번호는 시작 시 프로세스 환경에서 제거되며, URL은 로그나 결과에 표시되기 전에 자격 증명이 삭제됩니다.

컨테이너

docker run -i --rm \
  -e CALIBRE_WEB_URL=https://books.example.com \
  -e CALIBRE_WEB_USERNAME=reader \
  -e CALIBRE_WEB_PASSWORD=... \
  ghcr.io/ni-c/calibreweb-mcp

개발

npm install
npm test            # unit tests against a stubbed OPDS feed, no instance needed
npm run lint
npm run build

자세한 내용은 CONTRIBUTING.md를 참조하세요.

릴리스

1. CHANGELOG.md를 업데이트하고 package.json(+ lockfile)에서 버전을 올립니다.

2. npm run lint && npm run test:coverage && npm run build

3. 릴리스 태그: git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

라이선스

MIT