Calibre-Web

calibreweb-mcp

セルフホスト可能な電子書籍ライブラリの Web UI、Calibre-Web（および Calibre-Web Automated）向けの、読み取り専用の Model Context Protocol（MCP）サーバーです。

Claude Code、Claude Desktop、Codex などの MCP クライアントからライブラリを検索したり、 厳選されたビューや本棚を閲覧したり、形式ごとのダウンロードリンクをたどったり、表紙画像を会話に直接取り込んだりできます。書き込みは一切行いません。すべてのツールは GET リクエストです。

ツール数は最大で 6 個ですが、必ず 6 個使う必要はありません。CALIBRE_WEB_ALLOW_TOOLS=essential を設定すると、厳選された 5 個のツールだけが登録されます。モデルは 6 個より 5 個のほうが、適切なツールをはるかに確実に選べます。詳しくは 読み込むツールの選び方をご覧ください。

Calibre-Web には REST API がありません。安定した機械可読インターフェースは、電子書籍リーダーアプリ向けに提供される OPDS カタログフィードのみです。このサーバーはこのフィードを使用します。入力は HTTP Basic 認証付きの Atom XML、出力は構造化された書籍データです。

特長

Calibre-Web に存在しなかった API。 Calibre-Web には REST API がありません。安定した機械向けインターフェースは、電子書籍リーダーアプリ向けに構築された OPDS Atom フィードのみです。このツールはそのフィードを解析し、数値 ID、形式ごとのダウンロード URL、長さを制限した概要を含む構造化された書籍データに変換します。

設計上、読み取り専用。 6 個すべてのツールが GET リクエストです。リダイレクトは拒否されるため、Basic 認証情報が送信されることはありません。DOCTYPE を含む XML は無条件に拒否され、href は設定済みのオリジンに制限されます。また、メタデータには信頼できないデータであることが明示されます。

必要条件

• Node.js 22 以降
• Calibre-Web のインスタンス（現在の linuxserver/calibre-web イメージを使用して開発されています。Calibre-Web Automated も同様に動作します）
• サーバー用の Calibre-Web ユーザー。OPDS フィードは通常の Web ログインで認証されるため、管理者アカウントではなく、閲覧およびダウンロードのロールだけを持つ専用アカウントを使用してください。インスタンスで匿名閲覧が許可されている場合は、認証情報なしでもサーバーを実行できます。

設定

変数	必須	説明
CALIBRE_WEB_URL	はい	インスタンスのルート URL です。例：https://books.example.com。/opds パスは自動的に追加されます。
CALIBRE_WEB_USERNAME	はい¹	Calibre-Web アカウントのユーザー名です。
CALIBRE_WEB_PASSWORD	はい¹	そのアカウントのパスワード（Web ログイン用パスワード）です。
CALIBRE_WEB_INSECURE_TLS	いいえ	自己署名証明書を許可するには true を指定します。設定したホストのみに適用されます。
CALIBRE_WEB_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* プレフィックス、または厳選されたプリセットを指定する essential
CALIBRE_WEB_DENY_TOOLS	いいえ	同じ構文で指定します。CALIBRE_WEB_ALLOW_TOOLS で残ったツールから除外されます。

¹ 匿名閲覧を許可するインスタンスでは、両方とも未設定にしてください。片方だけを設定すると、構成エラーになります。

読み込むツールの選択

CALIBRE_WEB_ALLOW_TOOLS と CALIBRE_WEB_DENY_TOOLS には、カンマ区切りのツール名を指定します。 末尾の * は、ファミリー全体に一致します。essential は、次の 5 つのツールを厳選したプリセットです：search_books、list_books、list_shelves、get_shelf_books、get_stats。

CALIBRE_WEB_ALLOW_TOOLS=essential
CALIBRE_WEB_ALLOW_TOOLS=search_books,list_shelves
CALIBRE_WEB_DENY_TOOLS=get_cover

一致するツールがない項目があると、該当項目を示して起動が中止されるため、タイプミスによってツールが気付かれないまま非表示になることはありません。存在しないツールを環境変数のせいだと誰かが突き止める必要もありません。フィルターされたツールは登録されないため、tools/list にも表示されず、tools/call からも不明なツールとして扱われます。

これらのサーバーを複数同時に実行する場合は、mcp-hub がもうひとつの選択肢です。その /hub エンドポイントは、各サーバーのツールを 6 つのメタツールで置き換えます。

インストール

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 = "..." }

Docker

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

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、Web 版 Claude、Cursor、LibreChat）は、mcp-hub を通じて calibreweb-mcp に接続します。1 つのコンテナーで複数の stdio MCP サーバーを Streamable HTTP 経由で提供でき、単一のパスワードによる OAuth 2.1 ログインと、OAuth を利用できないクライアント向けの長期間有効なトークンを備えています。/hub エンドポイントは、すべてのサーバーを 6 つのメタツールの背後に配置するため、モデルのコンテキストに N 個分のツールスキーマを含めることなく、1 つのコネクターからすべてのサーバーに接続できます。また、両方のプロトコルリビジョンに対応しているため、このサーバーが尋ねる質問は、mcp-hub を経由して相手側のユーザーに届きます。

その /config/mcp.json は Claude Code の形式を使うため、エントリーにはすでにあるものをそのまま使用できます。

{
  "mcpServers": {
    "calibreweb": {
      "command": "npx",
      "args": ["-y", "calibreweb-mcp"],
      "env": { "CALIBRE_WEB_ALLOW_TOOLS": "essential" },
      "denyTools": ["get_cover"]
    }
  }
}

ここでの allowTools と denyTools は、ハブ独自のサーバーごとのフィルターです。env 内の *_ALLOW_TOOLS とは異なります。その違いと、そこで起こりやすい間違いについては、クライアントガイドをご覧ください。

ツール

すべてのツールは読み取り専用です（readOnlyHint: true）。

ツール	説明
search_books	タイトル、著者、シリーズ、出版社、タグで検索します。Calibre-Webはすべての一致結果を一度に返します。結果数はクライアント側で制限され（limit、既定値は50）、実際の一致件数も報告されます。
list_books	ビュー別に書籍を一覧表示します：new（既定）、hot、rated、discover（ランダム）、read、unread、all（任意で頭文字による絞り込みが可能）。
list_shelves	公開されている本棚と、設定済みユーザー自身の本棚を一覧表示します。
get_shelf_books	本棚にある書籍を、本棚の順序で取得します。
get_cover	書籍の表紙を、クライアントが表示できる画像として返します。
get_stats	書籍、著者、カテゴリ、シリーズの合計数を返します。

書籍エントリには、著者、タグ、シリーズ（巻数を含む）、評価、長さを制限した概要、表紙のURL、形式ごとのダウンロードURLが含まれます。モデル自体がEPUBをダウンロードする理由はないため、人間が開けるリンクをそのまま利用できます。

構造化出力

すべてのツールはoutputSchemaを宣言し、テキストブロックとともにstructuredContentを返すため、クライアントは文章を解析せずに結果を利用できます。

{
  "untrusted": true,
  "source": "calibre-web",
  "totalFound": 2,
  "truncated": false,
  "books": [{ "id": 7, "title": "Dune", "authors": ["Frank Herbert"] }],
  "notes": ["Book titles, authors, tags, series and summaries come from …"],
}

untrustedマーカーは、notes内の行だけでなくフィールドとして設けています。そうしないと、構造化データ側を読むクライアントは、文の一覧から警告を探す必要があるためです。このマーカーを含まない2つのツールはget_statsとget_coverです。前者は、このサーバーが数値であることを確認した4つのカウンターを返します。後者は、ID、4項目からなる許可リスト内のメディアタイプ、バイト数を報告します。画像自体は、クライアントが描画するコンテンツブロックに残ります。

予算を超過した結果では、従来どおり書籍の概要が省略されます。それでも不十分な場合は、上限で切り詰めたJSONではなく、エラーになります。解析不能なテキストはテキストブロックでは許容できましたが、structuredContentには格納できません。また、2つのチャネルは同じ値を保持する必要があります。

ページネーション

フィードは、インスタンスの 1ページあたりの書籍数 設定（既定値は60）に従ってページ分割されます。ページサイズはクライアントから変更できません。さらにページがある場合、すべての一覧でpagination.nextOffsetが返されます。次の呼び出しでは、これをoffsetとして渡してください。discoverビューはランダムな選択結果であり、ページ分割されません。

あえて公開していない機能

• 書き込み機能はありません。 OPDSフィードにもなく、このサーバーで追加することもありません。
• ファイルのダウンロード機能はありません。 ツールが返すのはダウンロードURLであり、電子書籍のデータではありません。
• ファセットによる閲覧機能はありません（著者、シリーズ、タグ、出版社、言語、形式を、それぞれ独立したインデックスフィードとして提供する機能）。これらの検索にはsearch_booksを利用できます。対応するルートは存在し、実際の利用例があれば、それらのツールを追加できます。

安全性

• サーバーは構造上読み取り専用です。GET リクエストのみを使用し、状態は一切保持しません。
• 書籍のメタデータは信頼できないサードパーティーデータです。すべての結果にその旨を記載し、制御文字を除去します。また、XML エンティティの処理は無効になっており、DOCTYPE やエンティティを宣言しているドキュメントは拒否されます。
• 応答は解析前（フィードは 8 MB、表紙は 1 MB）と、モデルに渡す前（書籍ごとおよび応答ごとの上限）の両方でサイズを制限します。
• フィードの href は、設定されたオリジンに http(s) 経由で解決される場合にのみ引き渡されます。悪意のあるフィードが javascript:、file:、またはクロスオリジン URL を結果に埋め込むことはできません。
• リダイレクトは拒否されるため、Basic 認証情報が別のホストに再送信されることはありません。表紙は、実際の画像コンテンツタイプの場合にのみ引き渡されます。
• 起動時にパスワードはプロセス環境から消去され、URL はログや結果に表示される前に認証情報が伏せられます。

ドキュメント

詳しいガイド、ツールリファレンス、安全性に関する注意事項は calibreweb-mcp.ni-c.de（ソースは docs/）をご覧ください。

開発

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 のバージョン（およびロックファイル）を更新します。
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

貢献

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.md をご覧ください。 脆弱性については、公開 Issue ではなく 非公開での報告 をご利用ください。ポリシーは SECURITY.md に記載されています。

ライセンス

MIT © Willi Thiel