Calibre MCP

既存の Calibre 電子書籍ライブラリのための読み取り専用 Model Context Protocol サーバーです。

Calibre MCP を使用すると、MCP 互換クライアントは書籍メタデータの検索、Calibre の全文インデックスのクエリ、書籍詳細の確認、ライブラリカテゴリの閲覧、関連書籍の発見ができます。metadata.db を直接読み取るのではなく、Calibre がサポートする calibredb コマンドラインインターフェースを使用します。

機能

• Calibre の検索言語を使用したメタデータ検索

• 一致するスニペット付きの全文検索

• 個々の書籍の詳細なメタデータ

• 最近追加された書籍

• 著者、タグ、シリーズ、出版社、言語カテゴリ

• 関連書籍の発見

• 書籍、検索、ライブラリステータスのための MCP リソース

• オプションの Calibre Content Server リンク

• インメモリ TTL キャッシュ

• Streamable HTTP トランスポート

• Podman Quadlet デプロイメント

• メタデータを変更する MCP ツールなし

Related MCP server: calibre-manager

利用可能なツール

MCP リソース

要件

• metadata.db を持つ Calibre ライブラリ

• Calibre 9.x

• Python 3.11 以降

• Streamable HTTP をサポートする MCP クライアント

• 同梱の Quadlet デプロイメント用の Podman と systemd

全文ツールを使用するには、Calibre の全文インデックスが有効で完了している必要があります。

Podman Quadlet によるクイックスタート

1. リポジトリをクローン

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

2. Calibre ライブラリを確認

提供された Quadlet は以下を前提としています:

/tank/media/Books

ライブラリデータベースが存在することを確認:

test -f /tank/media/Books/metadata.db && echo "Calibre library found"

3. ライブラリの所有者を特定

stat -c 'uid=%u gid=%g owner=%U:%G' /tank/media/Books

quadlet/calibre-mcp.container を編集し、User= を返された数値の UID と GID に設定:

User=1000:1000

ホストのライブラリパスが異なる場合は、それも変更:

Volume=/tank/media/Books:/books

4. イメージをビルド

sudo podman build \
  --build-arg CALIBRE_VERSION=9.11.0 \
  -t localhost/calibre-mcp:1.0.0 .

5. Quadlet をインストール

sudo mkdir -p /etc/containers/systemd

sudo cp quadlet/calibre-mcp.container \
  /etc/containers/systemd/calibre-mcp.container

sudo systemctl daemon-reload
sudo systemctl start calibre-mcp.service

systemctl enable calibre-mcp.service を実行しないでください。生成されたサービスは一時的なものです。Quadlet の [Install] セクションが起動時の依存関係を作成します。

6. デプロイメントを検証

sudo systemctl status calibre-mcp.service --no-pager
sudo journalctl -u calibre-mcp.service -n 100 --no-pager
sudo podman ps --filter name=calibre-mcp

コンテナ内の Calibre を確認:

sudo podman exec calibre-mcp \
  calibredb list \
  --with-library /books \
  --for-machine \
  --fields title \
  --limit 1

sudo podman exec calibre-mcp \
  calibredb fts_index status \
  --with-library /books

デフォルトのエンドポイントは:

http://localhost:8008/mcp

MCP Inspector でテスト

npx @modelcontextprotocol/inspector

Streamable HTTP を選択し、接続先:

http://YOUR_SERVER:8008/mcp

メタデータ検索の例:

{
  "query": "author:asimov",
  "limit": 10
}

全文検索の例:

{
  "query": "zero trust architecture",
  "limit": 10
}

制限付き全文検索の例:

{
  "query": "encryption",
  "limit": 10,
  "restrict_to": "search:tags:security"
}

MCP クライアントを接続

サーバーが公開する Streamable HTTP エンドポイントを使用:

http://YOUR_SERVER:8008/mcp

クライアント設定の形式はさまざまです。クライアントの MCP ドキュメントを参照し、stdio やレガシー SSE ではなく Streamable HTTP を選択してください。

Calibre 検索の例

search_books は Calibre の検索式を受け入れます:

author:asimov
title:"i robot"
tags:history
series:"Discworld"
publisher:penguin
languages:eng
rating:>=4

空のクエリは、結果制限の対象となるすべての書籍を返します。

オプションの Content Server リンク

既存の Calibre Content Server の URL を Quadlet に設定:

Environment=CALIBRE_CONTENT_SERVER_URL=http://mini-nas:8083

設定すると、メタデータ結果にブラウザとフォーマットダウンロードのリンクが含まれます。

設定

ライブラリマウントが書き込み可能な理由

Calibre は、ライブラリファイルシステムが大文字小文字を区別するかどうかを、ライブラリのルートにプローブファイルを一時的に作成して削除することで確認します。そのため、バインドマウントを読み取り専用にすることはできません。

このサーバーは、以下のような Calibre コマンドを呼び出すツールを公開しないため、機能的には読み取り専用のままです:

• add

• remove

• set_metadata

• add_format

• remove_format

ライブラリを所有する同じ非特権 UID と GID でコンテナを実行してください。環境が特に必要としない限り、root として実行しないでください。

セキュリティ

• ポート 8008 は、信頼できる LAN または Tailscale クライアントに限定してください。

• エンドポイントをパブリックインターネットに直接公開しないでください。

• このデプロイメントでは、Streamable HTTP は認証を追加しません。

• より広範囲に公開する前に、認証付きリバースプロキシをサービスの前に配置してください。

• 移動するコンテナタグではなく、リリースバージョンを固定してください。

• 脆弱性を報告する前に SECURITY.md を確認してください。

レッドチーム強化（ラウンド1）

10 の敵対的攻撃ベクトルが失敗するテストで証明され、修正されました。 tests/attack_round1_test.py の各 TestAttack_* テストは、そのベクトルに対する恒久的な回帰フィクスチャです。

このラウンドで検証された既知の安全な表面: シェルインジェクション（リスト argv、shell=True なし）、オプション値インジェクション（--sort-by/--categories/--restrict-to は Calibre のパーサーで先頭ダッシュの値を拒否）、リソース URI パストラバーサル（数値以外の ID は拒否）、結果制限のクランプ（_limit）、キャッシュの競合状態（ロックで保護）。

レッドチーム強化（ラウンド2）

6 つの入力形状検証ベクトルが証明され、修正されました。フィクスチャは tests/attack_round2_test.py にあります。

レッドチーム強化（ラウンド3）

3つのエラーパス堅牢性ベクトルが実証され、修正された。フィクスチャは tests/attack_round3_test.py にある。

レッドチーム強化（ラウンド4）

2つの並行性/プロセスフラッドベクトルが実証され、修正された。フィクスチャは tests/attack_round4_test.py にある。

レッドチーム強化（ラウンド5 — 最終検証）

新たな脆弱性はゼロ。カバレッジギャップ監査により、ラウンド1〜4でまだカバーされていないすべてのエントリーポイントを対象とする11件の検証テスト（tests/attack_round5_test.py）が追加された — search_resource、book_resource（非数値、トラバーサル類似、範囲内）、status_resource、library_status、list_recent_books、clear_cache、search_fulltext のリストペイロード、ゼロ/負のリミット、TTLゼロのキャッシュ無効化、空白クエリ。すべて即座に合格し、ラウンド1〜4の防御がツール/リソース全体の表面で有効であることが確認された。

2件のデプロイ姿勢に関するドキュメント指摘が SECURITY.md に記録された（コード変更なし）：Containerfile には USER ディレクティブがない（Quadlet の外でビルドすると root として実行される。Quadlet は User=1000:1000 を設定する）、また Quadlet は SecurityLabelDisable=true を設定する（SELinux ラベル分離はオフ）。

ローカル開発

仮想環境を作成する:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest ruff

テストを実行する:

pytest

lintチェックを実行する:

ruff check .

サーバーをローカルで起動する:

export CALIBRE_LIBRARY_PATH="/path/to/Calibre Library"
python server.py

プロジェクトの状態

バージョン 1.0.0 は、個人および信頼できるネットワークへのデプロイに適している。公開APIは将来のマイナーリリースで追加のツールやリソースが増える可能性があるが、既存のツール名と引数の形状は、実用的な範囲で安定に保たれる。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.md を参照してください。

ライセンス

MITライセンス の下で公開されています。